browser.debugger

תיאור

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

הרשאות

debugger

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

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

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

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

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

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

אחרי שמצורף יעד, אפשר להשתמש ב-API‏ browser.debugger כדי לשלוח פקודות של פרוטוקול כלי הפיתוח ל-Chrome‏ (CDP) ליעד נתון. הסבר מפורט על CDP חורג מהיקף המסמך הזה. כדי לקבל מידע נוסף על CDP, אפשר לעיין במסמכי התיעוד הרשמיים של CDP.

יעדים

יעדים מייצגים משהו שמבצעים בו ניפוי באגים – זה יכול לכלול כרטיסייה, iframe או worker. כל יעד מזוהה על ידי מזהה ייחודי אוניברסלי (UUID) ויש לו סוג משויך (כמו iframe,‏ shared_worker ועוד).

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

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

מטעמי אבטחה, ה-API‏ browser.debugger לא מספק גישה לכל הדומיינים של פרוטוקול כלי הפיתוח ל-Chrome. הדומיינים הזמינים הם: Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Runtime, Storage, Target, Tracing, WebAudio, ו-WebAuthn.

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

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

כדי לצרף לכל המסגרות, צריך לטפל בכל סוג של מסגרת בנפרד:

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

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

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

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

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

browser.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 browser.debugger.sendCommand(session, "Runtime.enable");
  }
});

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

await browser.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 הזה, מתקינים את הדוגמה של Debugger 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

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

מאפיינים

  • מצורף

    בוליאני

    הערך הוא True אם מאתר הבאגים כבר צורף.

  • extensionId

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

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

  • faviconUrl

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

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

  • id [מזהה]

    מחרוזת

    מזהה היעד.

  • tabId

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

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

  • title

    מחרוזת

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

  • סוג היעד.

  • url

    מחרוזת

    כתובת ה-URL ליעד.

TargetInfoType

‫Chrome 44 ואילך

סוג היעד.

ספירה

‫"page"

‫"background_page"

‫worker

'אחר'

Methods

attach()

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

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

פרמטרים

  • יעד

    Debuggee

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

  • requiredVersion

    מחרוזת

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

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

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

detach()

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

מנתק את מאתר הבאגים מהיעד שצוין.

פרמטרים

  • יעד

    Debuggee

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

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

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

getTargets()

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

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

החזרות

sendCommand()

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

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

פרמטרים

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

  • method

    מחרוזת

    שם ה-method. צריך לבחור אחת מהשיטות שמוגדרות בפרוטוקול לניפוי באגים מרחוק.

  • commandParams

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

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

החזרות

  • Promise<object | undefined>

    ‫Chrome 96 ואילך

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

אירועים

onDetach

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

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

פרמטרים

onEvent

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

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

פרמטרים

  • callback

    פונקציה

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

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

    • method

      מחרוזת

    • params

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