chrome.debugger

תיאור

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

הרשאות

debugger

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

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

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

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

יעדים

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

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

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

מטעמי אבטחה, ה-API chrome.debugger לא מאפשר גישה לכל הדומיינים של הפרוטוקולים של כלי הפיתוח ל-Chrome. הדומיינים הזמינים הם: Accessibility, DOMDebugger, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, DOMSnapshot, WebAudioWebAuthn

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

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

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

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

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

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

החל מגרסה 125 של Chrome, ה-API של chrome.debugger תומך בסשנים שטוחים. כך תוכלו להוסיף עוד יעדים בתור ילדים לסשן הראשי של ניפוי הבאגים, ולשלוח להם הודעות בלי צורך בקריאה נוספת אל 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 }]
});

דוגמאות

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

סוגים

Debuggee

מזהה של ניפוי באגים. יש לציין TabId, extensionId או targetId

תכונות

  • extensionId

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

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

  • tabId

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

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

  • targetId

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

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

DebuggerSession

Chrome מגרסה 125 ואילך

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

תכונות

  • extensionId

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

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

  • sessionId

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

    המזהה האטום של הסשן של פרוטוקול Chrome DevTools. משמש לזיהוי של סשן צאצא בתוך סשן הבסיס שזוהה באמצעות TabId, extensionId או targetId.

  • tabId

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

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

  • targetId

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

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

DetachReason

Chrome 44 ואילך

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

טיפוסים בני מנייה (enum)

"target_closed"

"canceled_by_user"

TargetInfo

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

תכונות

  • מחובר

    boolean

    True אם הכלי לניפוי באגים כבר מצורף.

  • extensionId

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

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

  • faviconUrl

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

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

  • id

    string

    מזהה יעד.

  • tabId

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

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

  • title

    string

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

  • סוג היעד.

  • כתובת אתר

    string

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

TargetInfoType

Chrome 44 ואילך

סוג היעד.

טיפוסים בני מנייה (enum)

"background_page"

"worker"

שיטות

attach()

הבטחה 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

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

פרמטרים

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

  • requiredVersion

    string

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 96 ומעלה

    יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

detach()

הבטחה 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

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

פרמטרים

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 96 ומעלה

    יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

getTargets()

הבטחה 
chrome.debugger.getTargets(
  callback?: function,
)

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    (result: TargetInfo[])=>void

    • תוצאה אחת

      TargetInfo[]

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

החזרות

  • Promise<TargetInfo[]>

    Chrome 96 ומעלה

    יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

sendCommand()

הבטחה 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

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

פרמטרים

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

  • method

    string

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

  • commandParams

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

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    (result?: object)=>void

    • תוצאה אחת

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

      אובייקט JSON עם התגובה. מבנה התשובה משתנה בהתאם לשם השיטה, והוא מוגדר על ידי המאפיין Returns של תיאור הפקודה בפרוטוקול לניפוי באגים מרחוק.

החזרות

  • Promise<object|undefined>

    Chrome 96 ומעלה

    יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

אירועים

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

      string

    • params

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