chrome.debugger

תיאור

ממשק ה-API של chrome.debugger משמש כאמצעי תחבורה חלופי עבור פרוטוקול ניפוי השגיאות מרחוק של Chrome. השתמשו ב-chrome.debugger כדי לצרף לטאב אחד או יותר כדי לבצע אינטראקציה עם רשת הכלים, לאתר באגים ב-JavaScript, לשנות את ה-DOM וה-CSS ועוד. השתמש בDebuggee נֶכֶסtabId כדי למקד טאבים עםsendCommand ולנתב אירועים לפיtabId מִןonEvent שיחות חוזרות.

הרשאות

debugger

עליך להצהיר על ההרשאה "debugger" במניפסט של התוסף שלך כדי להשתמש ב-API זה.

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

הגבלות מדיניות ארגוניות

במכשירים ארגוניים, מדיניות מסוימת יכולה להגביל את הרחבות מלצרף את ניפוי הבאגים באמצעות מודל הכל-או-כלום בזמן החיבור (chrome.debugger.attach() ):

  • הגבלות אירוח: אם מדיניות ארגוניתExtensionSettings מגדיר מארחים חסומים (runtime_blocked_hosts ) עבור הארכה, chrome.debugger.attach() חסום בכל היעדים עם השגיאה"Host access is restricted by policy." (גם אם מקורות בודדים נמצאים בruntime_allowed_hosts ).
  • מדיניות צילום מסך ו-DLP: אם מדיניות ארגוניתDisableScreenshots מבטל צילום מסך או שכללי מניעת אובדן נתונים (DLP) חלים על היעד, chrome.debugger.attach() נכשל עם השגיאה"Screenshot capture is restricted by policy.".

מושגים ושימוש

לאחר החיבור, ממשק ה-API של chrome.debugger מאפשר לך לשלוח פקודות של Chrome DevTools Protocol (CDP) ליעד נתון. הסבר מעמיק של ה-CDP אינו תחום התיעוד הזה - למידע נוסף על CDP עיינו בתיעוד הרשמי של ה-CDP.

יעדים

מטרות מייצגות משהו שמבוצע ניפוי באגים - זה יכול לכלול טאב, iframe או Worker. כל יעד מזוהה על ידי UUID ויש לו סוג משויך (כגון iframe, shared_worker ועוד).

בתוך יעד, ייתכנו מספר הקשרים של ביצוע - לדוגמה, מסגרות iframe של אותו תהליך אינן מקבלות יעד ייחודי אלא מיוצגות כהקשרים שונים שניתן לגשת אליהם מאותו יעד.

דומיינים מוגבלים

מסיבות אבטחה, ממשק ה-API של chrome.debugger אינו מספק גישה לכל דומייני פרוטוקול Chrome DevTools. הדומיינים הזמינים הם: נְגִישׁוּת ,ביקורות, CacheStorage, לְנַחֵם ,CSS, מסד נתונים, ניפוי באגים, DOM ,DOMDebugger, DOMSnapshot ,אמולציה, לְהָבִיא, IO, קֶלֶט ,מְפַקֵחַ, עֵץ, רֶשֶׁת, שכבת-על ,עַמוּד, ביצועים, יוצר פרופילים ,זמן ריצה, אִחסוּן, יַעַד, מַעֲקָב ,WebAudio, וWebAuthn.

עבודה עם מסגרות

אין מיפוי חד-פעמי של מסגרות ליעדים. בתוך כרטיסייה אחת, מספר מסגרות תהליך זהות עשויות לחלוק את אותה מטרה אך להשתמש בהקשר ביצוע שונה. מצד שני, ייתכן שייווצר יעד חדש עבור iframe מחוץ לתהליך.

כדי לחבר לכל המסגרות, עליך לטפל בכל סוג מסגרת בנפרד:

  • כדי לזהות הקשרים חדשים של ביצוע שמשויכים לאותם פריימים של תהליך, צריך להאזין לאירוע Runtime.executionContextCreated.

  • כדי לזהות פריימים מחוץ לתהליך, פועלים לפי השלבים לצירוף ליעדים קשורים.

אחרי שמתחברים ליעד, יכול להיות שתרצו להתחבר ליעדים קשורים נוספים, כולל מסגרות צאצא מחוץ לתהליך או רכיבי worker משויכים.

החל מגרסה 125 של Chrome, ‏chrome.debugger API תומך בפעילויות שטוחות. כך תוכלו להוסיף עוד יעדים כצאצאים לסשן הניפוי הראשי ולשלוח להם הודעות בלי שתצטרכו לבצע עוד קריאה ל-chrome.debugger.attach. במקום זאת, אפשר להוסיף מאפיין sessionId כשמתקשרים אל chrome.debugger.sendCommand כדי לזהות את יעד הצאצא שאליו רוצים לשלוח פקודה.

כדי לצרף באופן אוטומטי למסגרות צאצא מחוץ לתהליך, קודם צריך להוסיף מאזין לאירוע Target.attachedToTarget:

chrome.debugger.onEvent.addListener((source, method, params) => {
  if (method === "Target.attachedToTarget") {
    // `source` identifies the parent session, but we need to construct a new
    // identifier for the child session
    const session = { ...source, sessionId: params.sessionId };

    // Call any needed CDP commands for the child session
    await chrome.debugger.sendCommand(session, "Runtime.enable");
  }
});

לאחר מכן, מפעילים את הצירוף האוטומטי על ידי שליחת הפקודה Target.setAutoAttach עם האפשרות flatten שמוגדרת לערך true:

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

ההצמדה האוטומטית מתבצעת רק למסגרות שהיעד מודע להן, והיא מוגבלת למסגרות שהן צאצאים מיידיים של מסגרת שמשויכת אליה. לדוגמה, בהיררכיית המסגרות A -> B -> C (שבה כל המסגרות הן חוצות-מקור), קריאה ל-Target.setAutoAttach עבור היעד שמשויך ל-A תגרום לכך שהסשן ישויך גם ל-B. עם זאת, הפעולה הזו לא חוזרת על עצמה, ולכן צריך לקרוא גם ל-Target.setAutoAttach כדי ש-B יצורף לסשן ב-C.

דוגמאות

כדי לנסות את ה-API הזה, מתקינים את דוגמת ה-API של מאתר הבאגים ממאגר chrome-extension-samples.

סוגים

Debuggee

מזהה של רכיב לניפוי באגים. צריך לציין tabId, ‏ extensionId או targetId

מאפיינים

  • extensionId

    מחרוזת אופציונלי

    המזהה של התוסף שרוצים לבצע בו ניפוי באגים. אפשר להתחבר לדף הרקע של תוסף רק כשמשתמשים במתג --silent-debugger-extension-api של שורת הפקודה.

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שרוצים לנפות בה באגים.

  • targetId

    מחרוזת אופציונלי

    המזהה האטום של יעד ניפוי הבאגים.

DebuggerSession

‫Chrome 125 ואילך

מזהה סשן של ניפוי באגים. צריך לציין tabId, ‏ extensionId או targetId. בנוסף, אפשר לספק sessionId אופציונלי. אם sessionId מצוין לארגומנטים שנשלחים מ-onEvent, המשמעות היא שהאירוע מגיע מסשן של פרוטוקול צאצא בסשן של שורש ה-debuggee. אם מציינים sessionId כשמעבירים אותו אל sendCommand, הוא מכוון לסשן של פרוטוקול צאצא בסשן של ניפוי הבאגים ברמת הבסיס.

מאפיינים

  • extensionId

    מחרוזת אופציונלי

    המזהה של התוסף שרוצים לבצע בו ניפוי באגים. אפשר להתחבר לדף הרקע של תוסף רק כשמשתמשים במתג --silent-debugger-extension-api של שורת הפקודה.

  • sessionId

    מחרוזת אופציונלי

    המזהה האוטומטי של הסשן של פרוטוקול כלי הפיתוח ל-Chrome. מזהה סשן צאצא בסשן הבסיס שמזוהה על ידי tabId, ‏ extensionId או targetId.

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שרוצים לנפות בה באגים.

  • targetId

    מחרוזת אופציונלי

    המזהה האטום של יעד ניפוי הבאגים.

DetachReason

‫Chrome 44 ואילך

הסיבה לסיום החיבור.

ספירה

‫"target_closed"

‫"canceled_by_user"

TargetInfo

מידע על יעד ניפוי הבאגים

מאפיינים

  • מצורף

    בוליאני

    אמת אם ניפוי הבאגים כבר מחובר.

  • extensionId

    מחרוזת אופציונלי

    מזהה התוסף, מוגדר אם type = 'background_page'.

  • faviconUrl

    מחרוזת אופציונלי

    כתובת ה-URL של סמל האתר של היעד.

  • id [מזהה]

    מחרוזת

    מזהה יעד

  • tabId

    מספר אופציונלי

    מזהה הכרטיסייה, מוגדר אם סוג == 'דף'.

  • title

    מחרוזת

    כותרת עמוד היעד.

  • סוג היעד.

  • url

    מחרוזת

    כתובת URL של יעד.

TargetInfoType

‫Chrome 44 ואילך

סוג היעד.

ספירה

"עמוד"

"דף_רקע"

"עובד"

"אחר"

Methods

attach()

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
): Promise<void>

מצרף ניפוי באגים ליעד הנתון.

פרמטרים

  • יעד ניפוי באגים שאליו ברצונך לצרף.

  • requiredVersion

    מחרוזת

    גרסת פרוטוקול ניפוי שגיאות נדרשת ("0.1"). ניתן לצרף למאתר הבאגים רק עם גרסה ראשית תואמת וגרסה משנית גדולה או שווה ערך. ניתן למצוא רשימה של גרסאות הפרוטוקול כאן.

החזרות

  • Promise<void>

    כרום 96+

    נפתר לאחר שפעולת הצירוף מצליחה או נכשלת. ההבטחה נפתרת ללא ערך. אם הנספח ייכשל, ההבטחה תידחה.

detach()

chrome.debugger.detach(
  target: Debuggee,
): Promise<void>

מנתק את ניפוי הבאגים מהיעד הנתון.

פרמטרים

החזרות

  • Promise<void>

    כרום 96+

    נפתר לאחר שפעולת הניתוק מצליחה או נכשלת. ההבטחה נפתרת ללא ערך. אם הניתוק ייכשל, ההבטחה תידחה.

getTargets()

chrome.debugger.getTargets(): Promise<TargetInfo[]>

מחזירה את רשימת יעדי ניפוי השגיאות הזמינות.

החזרות

sendCommand()

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
): Promise<object | undefined>

שולח פקודה נתונה ליעד ניפוי השגיאות.

פרמטרים

  • יעד ניפוי באגים שאליו ברצונך לשלוח את הפקודה.

  • method

    מחרוזת

    שם השיטה. צריכה להיות אחת מהשיטות המוגדרות על ידי פרוטוקול ניפוי שגיאות מרחוק.

  • commandParams

    אובייקט אופציונלי

    אובייקט JSON עם פרמטרי בקשה. אובייקט זה חייב להתאים לסכימת הפרמטרים של ניפוי שגיאות מרחוק עבור השיטה הנתונה.

החזרות

  • הבטחה<אובייקט | לא מוגדר>

    כרום 96+

    גוף התגובה. אם תתרחש שגיאה בעת פרסום ההודעה, ההבטחה תידחה.

אירועים

onDetach

chrome.debugger.onDetach.addListener(
  callback: function,
)

מופעל כאשר הדפדפן מסיים את סשן ניפוי השגיאות עבור הכרטיסייה. זה קורה כאשר הכרטיסייה נסגרת או כאשר Chrome DevTools מופעל עבור הכרטיסייה המצורפת.

פרמטרים

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

מופעל בכל פעם שבא באגים בעיות יעד באירוע מכשור.

פרמטרים

  • callback

    פונקציה

    הפרמטר callback נראה כך: 

    (source: DebuggerSession, method: string, params?: object) => void

    • method

      מחרוזת

    • פרמטרים

      אובייקט אופציונלי