דף זה תורגם על ידי Cloud Translation API.

הוספת מודעות באמצעות מטא-נתונים של תזמון בלוקים של מודעות

במדריך הזה מוסבר איך להוסיף הפסקות לפרסום באמצעות השיטה Ad pod Timing Metadata (נתוני מטא של תזמון הפסקות לפרסום, ATM) כדי לאחזר את התזמון והמשך המדויקים של ההפסקות לפרסום, כולל מודעות לפני הסרטון.

כדי להוסיף מודעות לפני הסרטון ולנהל את החזרה לתוכן אחרי הפסקות לפרסומות באמצע הסרטון, מומלץ להפעיל את ממשקי ה-API הבאים:

‫Ad pod Timing Metadata (ATM) API: שאילתת תוצאות של החלטות לגבי רצפים של מודעות, כולל משך המודעות והמסכים השחורים.
נקודת הקצה של פלח המודעות: בקשה של פלחים של מודעות או של לוחות זמנים עם אפשרות להפסיק את בלוק המודעות הנוכחי.

לחלופין, באירועים של שידורים חיים עם מספר גבוה של צופים בו-זמנית, מומלץ להתקשר אל Early Ad Break Notification (EABN) API כדי לתזמן החלטות לגבי הצגת מודעות לפני הפסקת הפרסום.

דרישות מוקדמות

כדי להתחיל, צריך להגדיר אירוע של שידור חי מסוג הפניה אוטומטית להצגת מודעות בשידור חי (DAI). בוחרים באחת מהשיטות הבאות:

ממשק המשתמש של Ad Manager: הגדרת שידור חי ל-DAI.
‫Ad Manager API: משתמשים בספריית לקוח (אפשרויות זמינות) כדי לקרוא לשיטה LiveStreamEventService.createLiveStreamEvents. מגדירים את הפרמטר LiveStreamEvent.dynamicAdInsertionType לערך POD_SERVING_REDIRECT.

אחזור מקור נתוני התוכן

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

בדוגמה הבאה מועבר מזהה סשן של Google DAI למניפולטור של מניפסט:

https://MANIFEST_MANIPULATOR_URL/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY

כשמעבדים את הבקשה להפעלת תוכן הווידאו, מאחסנים את מזהה הסשן של Google DAI ואת CUSTOM_ASSET_KEY מהבקשה כדי להתכונן להוספת מודעות.

אחזור מטא-נתונים של תזמון בלוקים של מודעות

כדי לאחזר את התזמון של חבילת המודעות, פועלים לפי השלבים הבאים:

יצירת טוקן HMAC.
שולחים קריאה ל-ATM API עם אסימון HMAC.

יצירת טוקן HMAC חתום

כדי לאמת את הבקשות, צריך לבצע את השלבים הבאים:

יוצרים מחרוזת אסימון על ידי שרשור הפרמטרים הבאים בסדר אלפביתי, כשהם מופרדים באמצעות סימן הטילדה ~:

פרמטר	נדרש או אופציונלי	תיאור
`ad_break_id`	חובה	מחרוזת שאתם מציינים כדי לזהות את ההפסקה המסחרית, לדוגמה `ad-break-1`. למודעות לפני הסרטון, משתמשים ב-`preroll`.
`custom_asset_key`	חובה	מפתח הנכס המותאם אישית של האירוע בשידור חי.
`cust_params`	אופציונלי	פרמטרים מותאמים אישית לטירגוט. פרטים נוספים זמינים במאמר בנושא הוספת פרמטרים לטירגוט של מודעות לסטרימינג.
`exp`	חובה	הזמן שבו יפוג תוקף האסימון הזה, שנמדד כמספר השניות הכולל שחלף מאז ראשית זמן יוניקס.
`network_code`	חובה	קוד הרשת ב-Google Ad Manager. פרטים נוספים זמינים במאמר בנושא איתור פרטי חשבון Ad Manager.
`pd`	חובה	משך ההפסקה למודעה באלפיות השנייה. במודעות לפני הסרטון, Google DAI מבטל את הפרמטר הזה ומחליף אותו בהגדרות האירוע של השידור החי.
`scte35`	אופציונלי	אות SCTE-35 בקידוד Base64. מוודאים שהאות נכון. אם הערך שגוי, הודעה נשלחת לכותרת ה-HTTP‏ `X-Ad-Manager-Dai-Warning` בתגובה, והאות עדיין מועבר כדי ליצור הפסקה לפרסומות. פרטים נוספים על סמני הפסקות פרסומיות נתמכים זמינים במאמר בנושא שילוב HLS.

מורידים את מפתח האימות של Google DAI מסוג HMAC. לפרטים נוספים, ראו אימות בקשות של סטרימינג של וידאו ב-DAI.
משתמשים במפתח ה-HMAC שהורדתם כדי ליצור את חתימת SHA256 של מחרוזת האסימון.
משרשרים את מחרוזת הטוקן ואת החתימה שנוצרה.
מחילים קידוד URL על המחרוזת המחוברת. המחרוזת המקודדת היא טוקן HMAC חתום לאימות בקשות של Ad pod Timing Metadata (ATM) API.

בדוגמה הבאה נוצר אסימון HMAC חתום למודעות לפני הסרטון:

custom_asset_key="CUSTOM_ASSET_KEY"
exp="1750700000" # Expired on Mon Jun 23 2025 13:33:20 GMT-0400 (Eastern Daylight Time)
network_code="NETWORK_CODE"
ad_break_id="preroll"
pd="0" # Pod duration value is overridden by the livestream event settings.

# The HMAC authentication key associated with your livestream event in Google Ad Manager.
secret_key="24E96382584C328087546B0E8454F26158564E8466FD2BE3D8A996B38445876C"

# Concatenate the parameters, keep the parameters alphabetically ordered by name.
token_string="ad_break_id=${ad_break_id}~custom_asset_key=${custom_asset_key}~exp=${exp}~network_code=${network_code}~pd=${pd}"

# Calculate the SHA256 signature of the token_string.
hmac_signature=$(echo -n "$token_string" | openssl dgst -sha256 -hmac "$secret_key" | awk '{print $2}')

# Concatenate the token string and the signature.
signed_token="${token_string}~hmac=${hmac_signature}"

url_encode() {
    local string="${1}"
    local strlen=${#string}
    local encoded=""
    local pos c
    for (( pos=0 ; pos<strlen ; pos++ )); do
        c=${string:$pos:1}
        case "$c" in
            [-_.~a-zA-Z0-9] ) o="${c}" ;;
            *   ) printf -v o '%%%02x' "'$c"
        esac
        encoded+="${o}"
    done
    echo "${encoded}"
}

# Apply URL encoding to the concatenated string.
url_encoded_signed_token=$(url_encode "$signed_token")

echo "Signed HMAC token:"
echo "${url_encoded_signed_token}"

# Example output:
# ad_break_id%3Dpreroll~custom_asset_key%3DiYdOkYZdQ1KFULXSN0Gi7g~exp%3D1489680000~network_code%3D21775744923~pd%3D180000~pod_id%3D5~hmac%3D24E96382584C328087546B0E8454F26158564E8466FD2BE3D8A996B38445876C

בקשת מטא-נתונים של תזמון למודעות לפני סרטון

כדי לאמת את ההגדרות של הפרסומות שלפני הסרטון בשידור החי, אפשר להשתמש באפשרויות הבאות:

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

בדוגמה הבאה מוצגת בקשה למודעות לפני סרטון (pre-roll) דרך ATM:

curl "https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/pod.json?stream_id=SESSION_ID&ad_break_id=preroll&auth-token=your_signed_HMAC_token"

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

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

ניתוח מניפסט השידור החי כדי למצוא את סמני המודעות שמכילים את התזמון ואת משך הזמן של כל הפסקה למודעות באמצע הסרטון.
מפעילים את נקודת הקצה (endpoint) של ATM API כדי לבקש את משך הזמן המדויק של בלוק המודעות והמסך השחור. ה-API מחזיר אובייקט JSON עם תוצאות ההחלטה של בלוק המודעות.

בדוגמה הבאה מוצגת בקשה ל-ATM עבור מודעות באמצע הסרטון (mid-roll):

curl "https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/pod.json?stream_id=SESSION_ID&ad_break_id=AD_BREAK_ID&pd=AD_BREAK_DURATION&auth-token=your_signed_HMAC_token"

אם הפעולה בוצעה בהצלחה, הפלט ייראה כמו אובייקט ה-JSON הבא:

{
  "status": "final",
  "ads": [
    {
      "duration_ms": 5046,
      "variants": {
        "devrel1428000": {
          "segment_extension": "ts",
          "segment_durations": {
            "timescale": 1000,
            "values": [
              5045
            ]
          }
        },
        "devrel1928000": {
          "segment_extension": "ts",
          "segment_durations": {
            "timescale": 1000,
            "values": [
              5045
            ]
          }
        }
      }
    }
  ],
  "slate": {
    "duration_ms": 0,
    "variants": {
      "devrel1428000": {
        "segment_extension": "ts",
        "segment_durations": {
          "timescale": 1000,
          "values": [
            5005,
            ...
            5046
          ]
        }
      },
      "devrel1928000": {
        "segment_extension": "ts",
        "segment_durations": {
          "timescale": 1000,
          "values": [
            5005,
            ...
            5046
          ]
        }
      }
    }
  }
}

הוספת מודעות למניפסט של התוכן

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

זיהוי פלחים של הפסקות פרסום והוספת אי-רציפות

במהלך העיבוד של כל מניפסט של וריאנט, צריך לזהות את התגים EXT-X-CUE-IN ו-EXT-X-CUE-OUT בפיד, שמציינים את ההתחלה והסיום של הפסקת הפרסום.

מחליפים את התגים EXT-X-CUE-IN ו-EXT-X-CUE-OUT ברכיבי EXT-X-DISCONTINUITY כדי שנגן הווידאו של הלקוח יוכל לעבור בין תוכן למודעות.

במניפסט לדוגמה הבא, התגים EXT-X-CUE-IN ו-EXT-X-CUE-OUT מוחלפים:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.000,
contentorigin.com/1.ts
#EXTINF:5.000,
contentorigin.com/2.ts
#EXT-X-CUE-OUT:15.000
#EXTINF:5.000,
contentorigin.com/3.ts
#EXTINF:5.000,
contentorigin.com/4.ts
#EXTINF:5.000,
contentorigin.com/5.ts
#EXT-X-CUE-IN
#EXTINF:5.000,
contentorigin.com/6.ts
#EXTINF:5.000,
contentorigin.com/7.mp4
#EXTINF:5.000,
contentorigin.com/8.mp4

בדוגמה הבאה מוצג מניפסט שהוחלף:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.000,
contentorigin.com/1.ts
#EXTINF:5.000,
contentorigin.com/2.ts
#EXTINF:5.000,
#EXT-X-DISCONTINUITY
{... Insert ad segments here ...}
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
contentorigin.com/6.mp4
#EXTINF:5.000,
contentorigin.com/7.mp4
#EXTINF:5.000,
contentorigin.com/8.mp4

פלחים של מודעות דינמיות ב-Google לא מוצפנים. אם התוכן מוצפן, צריך להסיר את ההצפנה על ידי הוספת רכיב EXT-X-KEY:METHOD=NONE לפני פלח המודעה הראשון של כל הפסקה לפרסומות. בסוף הפסקת הפרסומות, מוסיפים שוב הצפנה על ידי הוספת תג EXT-X-KEY מתאים.

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

יצירת כתובות URL של פלחים לפרסום

מחליפים את פילוחי התוכן בין התגים EXT-X-DISCONTINUITY בכתובות URL לכל פלח מודעות. כדי לקבוע כמה מקטעי מודעות להוסיף, משתמשים בערך ads.segment_durations.values שמופיע בתגובת ה-JSON מ-ATM API.

כדי לסיים מוקדם את הצגת רצף המודעות כשמזוהה תג EXT-X-CUE-IN, מוסיפים את הפרמטר d= לכתובת ה-URL של פלח המודעה האחרון. הפרמטר הזה מקצר את הפלח כדי שלא ישפיע על ציר הזמן של נגן הווידאו של הלקוח.

בדוגמה הבאה מורכבת כתובת URL של פלח מודעה לפני הסרטון למניפסט. הערה: פלחי המודעות מתבססים על אינדקס שמתחיל בספרה אפס:

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/preroll/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

בדוגמה הבאה מוצג איך להרכיב כתובת URL של פלח מודעה באמצע הסרטון במניפסט:

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

בדוגמה הבאה מוסיפים פלחי מודעות למניפסט:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.00,
contentorigin.com/1.ts
#EXTINF:5.00,
contentorigin.com/2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/1.ts?stream_id=SESSION_ID
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/2.ts?stream_id=SESSION_ID
#EXT-X-DISCONTINUITY
#EXTINF:5.00,
contentorigin.com/6.mp4
#EXTINF:5.00,
contentorigin.com/7.mp4
#EXTINF:5.00,
contentorigin.com/8.mp4

בניית פלחים של לוח

כדי למלא את הפער בין המודעה לתוכן, מוסיפים קטעי לוח. משתמשים במערך slates.segment_durations.values מתגובת ה-JSON של ATM API כדי לקבוע את משך הזמן של כל פלח של לוח. אם צריך, חוזרים על רצף משכי הזמן של הפלחים כדי למלא את כל ההפסקה המסחרית.

בדוגמה הבאה מוצג פלח של לוח:

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/slate/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

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

ניהול החזרה לתוכן

אחרי שמוסיפים את כל פלחי המודעות, בוחרים באחת מהשיטות הבאות כדי לחזור לתוכן:

שיטה	תיאור	ההשפעה על נגן הווידאו של הלקוח
מילוי בפלחים של לוח	הוספת קטעי הלוח ושידור חוזר של הלוח. ממלא את משך הזמן ומוסיף רכיבי `EXT-X-DISCONTINUITY` בין כל איטרציה של לוח.	ללא אפקטים. נגן הווידאו חוזר לתוכן ללא ציר זמן ששונה.
התאמה מחדש באמצעות פלח יחיד של לוח	הוספה של מקטע יחיד של לוח. הפרמטר `d=` משמש למילוי משך הזמן עד להתחלת התוכן.	ללא אפקטים. נגן הווידאו חוזר לתוכן ללא ציר זמן ששונה.
החזרה מיידית	הוספת פלחים של תוכן.	ציר הזמן של נגן הווידאו משתנה. נגן הווידאו של הלקוח צריך לטפל בציר הזמן שמשתנה.

אופציונלי: תזמון של הפסקה למודעה

כדי לשפר את שיעור המילוי, צריך לשלוח הודעה על הפסקת פרסום מוקדמת (EABN) עם משך בלוק הפרסום, פרמטרים מותאמים אישית של טירגוט ונתוני אותות SCTE-35. פרטים נוספים זמינים במאמר בנושא שליחת התראות מוקדמות על הפסקות לפרסומות.