تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إدراج الإعلانات باستخدام البيانات الوصفية لتوقيت حزمة الإعلانات

يوضّح هذا الدليل كيفية إدراج فواصل إعلانية باستخدام طريقة "بيانات وصف توقيت حزمة الإعلانات" (ATM) لجلب التوقيت والمدة الدقيقَين للفواصل الإعلانية، بما في ذلك الإعلانات التمهيدية.

لإدراج إعلانات ما قبل التشغيل وإدارة العودة إلى المحتوى بعد فواصل الإعلانات أثناء التشغيل، ننصحك باستدعاء واجهات برمجة التطبيقات التالية:

واجهة برمجة التطبيقات الخاصة ببيانات Ad pod Timing Metadata (ATM): للاستعلام عن نتائج قرارات مجموعات الإعلانات المتسلسلة، بما في ذلك مدة الإعلان ومدّة شاشة الملء
نقطة نهاية شريحة الإعلان: لطلب شرائح إعلانات أو لوحات إعلانات مع خيار إنهاء حزمة الإعلانات الحالية.

اختياريًا، بالنسبة إلى أحداث البث المباشر التي تتضمّن عددًا كبيرًا من المستخدمين المتزامنين، ننصحك باستدعاء Early Ad Break Notification (EABN) API لجدولة قرارات الإعلانات قبل بدء فاصل الإعلانات.

المتطلبات الأساسية

لبدء استخدام هذه الميزة، يجب إعداد حدث بث مباشر لنوع "إدراج الإعلانات الديناميكية" (DAI) إعادة التوجيه لعرض الإعلانات ضمن البودكاست. اختَر إحدى الطرق التالية:

واجهة مستخدم "مدير الإعلانات": إعداد بث مباشر باستخدام إعلانات DAI
Ad Manager API: استخدِم مكتبة برامج للعميل (الخيارات المتاحة) لاستدعاء الطريقة LiveStreamEventService.createLiveStreamEvents. اضبط المَعلمة LiveStreamEvent.dynamicAdInsertionType على POD_SERVING_REDIRECT.

استرداد مجموعة بث المحتوى

عندما يختار المستخدم حدث بث مباشر، يرسل تطبيق العميل طلب بث إلى "مدير إعلانات Google". في ردّ البث، يستخرج التطبيق رقم تعريف جلسة 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 باستخدام رمز HMAC المميز.

إنشاء رمز مميّز مُوقَّع باستخدام HMAC

لإثبات صحة طلباتك، اتّبِع الخطوات التالية:

أنشئ سلسلة رموز مميزة من خلال ربط المَعلمات التالية بترتيب أبجدي، مع الفصل بينها بعلامة المد ~:

المَعلمة	مطلوبة أم اختيارية	الوصف
`ad_break_id`	مطلوب	سلسلة تحدّدها لتحديد فاصل الإعلان، مثل `ad-break-1`. بالنسبة إلى "إعلانات ما قبل التشغيل"، استخدِم `preroll`.
`custom_asset_key`	مطلوب	مفتاح الأصول المخصّص لحدث البث المباشر
`cust_params`	اختياري	مَعلمات الاستهداف المخصّص لمزيد من التفاصيل، اطّلِع على توفير معلَمات الاستهداف لتدفقك.
`exp`	مطلوب	الوقت الذي تنتهي فيه صلاحية هذا الرمز المميّز، ويُقاس بإجمالي عدد الثواني التي انقضت منذ بداية حقبة Unix.
`network_code`	مطلوب	رمز شبكة "مدير إعلانات Google" لمزيد من التفاصيل، يُرجى الاطّلاع على العثور على معلومات حساب "مدير إعلانات Google".
`pd`	مطلوب	مدة الفاصل الإعلاني بالمللي ثانية. بالنسبة إلى "إعلانات ما قبل التشغيل"، تتجاهل ميزة "إعلانات Google الديناميكية أثناء البث" هذه المَعلمة وتستخدِم إعدادات حدث البث المباشر.
`scte35`	اختياري	إشارة SCTE-35 مرمّزة باستخدام Base64 تأكَّد من صحة الإشارة. إذا كانت القيمة غير صحيحة، يتم إرسال رسالة إلى عنوان HTTP `X-Ad-Manager-Dai-Warning` في الردّ، ويستمر نشر الإشارة لإنشاء فاصل إعلاني. لمزيد من التفاصيل حول علامات فواصل الإعلانات المتوافقة، يُرجى الاطّلاع على عملية الدمج مع HLS.

نزِّل مفتاح مصادقة Google DAI من النوع HMAC. لمزيد من التفاصيل، يُرجى الاطّلاع على مصادقة طلبات بث الفيديو في "الإعلانات الديناميكية أثناء عرض الفيديو".
استخدِم مفتاح HMAC الذي تم تنزيله لإنشاء توقيع SHA256 لسلسلة الرموز المميزة.
اربط سلسلة الرمز المميز بالتوقيع الذي تم إنشاؤه.
تطبيق ترميز عنوان URL على السلسلة المتسلسلة السلسلة المرمّزة هي رمز HMAC موقَّع للمصادقة على طلبات واجهة برمجة التطبيقات الخاصة ببيانات وصف توقيت حزمة الإعلانات (ATM).

ينشئ المثال التالي رمزًا مميَّزًا موقَّعًا باستخدام 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.

يرسل المثال التالي طلبًا إلى 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"

طلب البيانات الوصفية لتوقيت "الإعلانات أثناء التشغيل"

لاسترداد بيانات وصفية خاصة بحزم الإعلانات في منتصف الفيديو، اتّبِع الخطوات التالية:

حلِّل ملف بيانات البث المباشر للعثور على علامات الإعلانات التي تتضمّن التوقيت والمدة لكل فاصل إعلاني أثناء التشغيل.
يمكنك طلب المدة الدقيقة لفترة عرض الإعلانات المتزامنة ولوحة الإعلانات من خلال نقطة نهاية واجهة برمجة التطبيقات الخاصة بأجهزة الصرّاف الآلي. تعرض واجهة برمجة التطبيقات عنصر JSON يتضمّن نتائج قرار حزمة الإعلانات.

يقدم المثال التالي طلبًا إلى "إدارة الزيارات" لعرض إعلانات أثناء التشغيل:

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.

لإنهاء حزمة إعلانات مبكرًا عند رصد علامة 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

إنشاء شرائح Slate

لملء الفجوة بين الإعلان والمحتوى، أدرِج مقاطع لوحية. استخدِم مصفوفة slates.segment_durations.values من استجابة JSON لواجهة برمجة تطبيقات ATM لتحديد مدة كل جزء من لوحة الإعلانات. كرِّر تسلسل مدة الفواصل الإعلانية حسب الحاجة لملء فاصل الإعلان بالكامل.

يجمع المثال التالي جزءًا من قائمة التشغيل:

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 لجميع التكرارات.

إدارة ميزة "الرجوع إلى المحتوى"

بعد إدراج جميع المقاطع من حزمة الإعلانات، اختَر إحدى الطريقتَين التاليتَين للعودة إلى بث المحتوى:

الطريقة	الوصف	التأثيرات على مشغّل الفيديو لدى العميل
الملء بشرائح Slate	يتم إدراج مقاطع اللوحة وتكرارها. يملأ المدة الزمنية ويدرج عناصر `EXT-X-DISCONTINUITY` بين كل تكرار للوحة.	بدون تأثيرات: يعود مشغّل الفيديو إلى المحتوى بدون تغيير المخطط الزمني.
إعادة المزامنة مع شريحة لوحة واحدة	تُدرج هذه السمة مقطعًا واحدًا من لوحة الإعلانات. يستخدم المَعلمة `d=` لملء المدة حتى بداية المحتوى.	بدون تأثيرات: يعود مشغّل الفيديو إلى المحتوى بدون تغيير المخطط الزمني.
الإرجاع الفوري	إدراج مقاطع المحتوى	يتم تغيير المخطط الزمني لمشغّل الفيديو. يجب أن يتعامل مشغّل الفيديو على جهاز العميل مع المخطط الزمني المعدَّل.

اختياري: جدولة فاصل إعلاني

لتحسين نسبة التعبئة، أرسِل إشعارًا مبكرًا بفاصل إعلاني (EABN) يتضمّن مدة سلسلة الإعلانات، ومعلمات الاستهداف المخصّصة، وبيانات إشارة SCTE-35. لمزيد من التفاصيل، يُرجى الاطّلاع على إرسال إشعارات بشأن فواصل إعلانية مبكرة.