این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

درج تبلیغات با متادیتای زمان بندی آگهی

این راهنما نحوه درج وقفه‌های تبلیغاتی را با استفاده از روش Ad Pod Timeming Metadata (ATM) برای واکشی زمان‌بندی و مدت زمان وقفه‌های تبلیغاتی، از جمله تبلیغات قبل از پخش، شرح می‌دهد.

برای درج آگهی‌های قبل از پخش و مدیریت بازگشت به محتوا پس از وقفه‌های تبلیغاتی میان فیلم، توصیه می‌کنیم APIهای زیر را فراخوانی کنید:

API زمان‌بندی فراداده آگهی (ATM) : نتایج تصمیم‌گیری غلاف آگهی، از جمله مدت زمان آگهی و جدول را جستجو کنید.
نقطه پایانی بخش تبلیغات : درخواست بخش‌های آگهی یا تخته سنگ با گزینه پایان دادن به غلاف آگهی فعلی.

به صورت اختیاری، برای رویدادهای پخش زنده همزمانی بالا، توصیه می‌کنیم با API Early Break Notification (EABN) تماس بگیرید تا قبل از شروع وقفه آگهی تصمیم‌گیری‌های تبلیغاتی را زمان‌بندی کنید.

پیش نیازها

برای شروع، به یک رویداد پخش زنده نیاز دارید که برای نوع درج آگهی پویا (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 تولید کنید.
با توکن HMAC با ATM API تماس بگیرید.

یک نشانه HMAC امضا شده ایجاد کنید

برای احراز هویت درخواست های خود، مراحل زیر را دنبال کنید:

با به هم پیوستن پارامترهای زیر به ترتیب حروف الفبا، که با یک tilde از هم جدا شده اند ~ یک رشته نشانه ایجاد کنید:

پارامتر	الزامی یا اختیاری	توضیحات
`ad_break_id`	مورد نیاز	رشته ای که برای شناسایی وقفه تبلیغاتی مشخص می کنید، برای مثال `ad-break-1` . برای تبلیغات قبل از پخش، `preroll` استفاده کنید.
`custom_asset_key`	مورد نیاز	کلید دارایی سفارشی رویداد پخش زنده.
`cust_params`	اختیاری	پارامترهای هدف گذاری سفارشی برای جزئیات بیشتر، به پارامترهای هدفمندی عرضه برای جریان خود مراجعه کنید.
`exp`	مورد نیاز	زمانی که این نشانه منقضی می شود، به عنوان تعداد کل ثانیه هایی که از دوره یونیکس گذشته است اندازه گیری می شود.
`network_code`	مورد نیاز	کد شبکه Google Ad Manager شما. برای جزئیات بیشتر، به یافتن اطلاعات حساب مدیر آگهی مراجعه کنید.
`pd`	مورد نیاز	مدت زمان استراحت آگهی بر حسب میلی ثانیه برای تبلیغات قبل از پخش، Google DAI این پارامتر را با تنظیمات رویداد پخش زنده شما لغو می کند.
`scte35`	اختیاری	سیگنال SCTE-35 با کد Base64. بررسی کنید که سیگنال صحیح است. در صورت نادرست بودن، پیامی به هدر HTTP `X-Ad-Manager-Dai-Warning` در پاسخ ارسال می شود و سیگنال همچنان برای ایجاد یک وقفه تبلیغاتی منتشر می شود. برای جزئیات بیشتر در مورد نشانگرهای استراحت پشتیبانی شده، به ادغام HLS مراجعه کنید.

کلید احراز هویت Google DAI خود را از نوع HMAC دانلود کنید. برای جزئیات بیشتر، احراز هویت درخواست‌های جریان ویدیویی DAI را ببینید.
از کلید HMAC دانلود شده خود برای ایجاد امضای SHA256 رشته توکن استفاده کنید.
رشته توکن و امضای تولید شده را به هم متصل کنید.
کدگذاری URL را به رشته پیوسته اعمال کنید. رشته کدگذاری شده، نشانه HMAC امضا شده برای احراز هویت درخواست‌های API زمان‌بندی فراداده آگهی (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 ارائه دهید.

مثال زیر یک درخواست 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"

فراداده زمان‌بندی را برای تبلیغات میان‌پول درخواست کنید

برای بازیابی فراداده غلاف آگهی برای پخش میانی، این مراحل را دنبال کنید:

مانیفست پخش زنده را تجزیه کنید تا نشانگرهای تبلیغاتی را پیدا کنید که شامل زمان و مدت زمان هر وقفه تبلیغاتی میان فیلم است.
با نقطه پایانی ATM ATM تماس بگیرید تا غلاف آگهی و مدت زمان فهرست دقیق را درخواست کنید. API یک شی JSON را با نتایج تصمیم غلاف آگهی برمی گرداند.

مثال زیر یک درخواست 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=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 DAI رمزگذاری نشده‌اند. اگر محتوای شما رمزگذاری شده است، با وارد کردن عنصر EXT-X-KEY:METHOD=NONE قبل از اولین بخش تبلیغاتی هر وقفه، رمزگذاری را حذف کنید. در پایان وقفه تبلیغاتی، با قرار دادن یک EXT-X-KEY مناسب، رمزگذاری را دوباره اضافه کنید.

زمان شروع، مدت زمان و فهرست وقفه تبلیغاتی آینده را پیگیری کنید.

URL های بخش تبلیغات بسازید

بخش‌های محتوا بین تگ‌های EXT-X-DISCONTINUITY را با URL برای هر بخش تبلیغ جایگزین کنید. برای تعیین تعداد بخش های تبلیغاتی برای درج، از ads.segment_durations.values ارائه شده در پاسخ JSON از ATM 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

مثال زیر یک نشانی وب بخش تبلیغات میان فیلم را به مانیفست مونتاژ می کند:

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 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 نگه دارید، به سازگاری پخش کننده ویدیوی مشتری خود و قابلیت ذخیره کش مراجعه کنید.

بازگشت به محتوا را مدیریت کنید

پس از درج همه بخش‌ها از غلاف تبلیغات، یکی از روش‌های زیر را برای انتقال مجدد به جریان محتوای خود انتخاب کنید:

روش	توضیحات	اثرات بر روی پخش کننده ویدیوی مشتری
با قطعات تخته سنگ پر کنید	قطعات تخته سنگ را وارد می کند و تخته سنگ را حلقه می کند. مدت زمان را پر می کند و عناصر `EXT-X-DISCONTINUITY` را بین هر تکرار تخته سنگ درج می کند.	بدون اثرات. پخش‌کننده ویدیو بدون تغییر جدول زمانی به محتوا برمی‌گردد.
با یک بخش تخته سنگی مجدداً تراز کنید	یک قطعه تخته سنگی را درج می کند. از پارامتر `d=` برای پر کردن مدت زمان تا شروع محتوا استفاده می کند.	بدون اثرات. پخش‌کننده ویدیو بدون تغییر جدول زمانی به محتوا برمی‌گردد.
بازگشت فوری	درج بخش های محتوا	جدول زمانی پخش کننده ویدیو تغییر کرده است. پخش کننده ویدیوی مشتری شما باید جدول زمانی تغییر یافته را کنترل کند.

اختیاری: یک وقفه تبلیغاتی را برنامه ریزی کنید

برای افزایش میزان پر شدن، یک اعلان وقفه اولیه تبلیغاتی (EABN) همراه با مدت زمان آگهی، پارامترهای هدف‌یابی سفارشی و داده‌های سیگنال SCTE-35 ارسال کنید. برای جزئیات بیشتر، به ارسال زودهنگام اعلان‌های وقفه تبلیغاتی مراجعه کنید.