راه‌اندازی با درج آگهی پویا در سرویس Pod

انتخاب پلاتفرم: HTML5 Android iOS tvOS Cast Roku

کیت‌های توسعه نرم‌افزار IMA ادغام آگهی‌های چندرسانه‌ای را در وب‌سایت‌ها و برنامه‌های شما ساده می‌کنند.

کیت‌های توسعه نرم‌افزار IMA می‌توانند از هر سرور آگهی مطابق با VAST درخواست آگهی کنند و بازپخش آگهی را در برنامه‌هایتان مدیریت کنند.

با کیت‌های توسعه نرم‌افزار IMA DAI، برنامه‌ها درخواست جاری‌سازی برای آگهی و محتوای ویدیویی برای محتوای ویدیو به‌درخواست یا محتوای زنده ارسال می‌کنند. سپس کیت توسعه نرم‌افزار یک جاری‌سازی ویدیویی ترکیبی را برمی‌گرداند، بنابراین نیازی نیست که جابه‌جایی بین آگهی و محتوای ویدیویی را در برنامه‌تان مدیریت کنید.

این راهنما نشان می‌دهد که چگونه بااستفاده از IMA DAI SDK برای CAF، یک جاری‌سازی «ارائه پاد» DAI را پخش کنید.

قبل‌از استفاده از این راهنما، با پروتکل گیرنده وب چارچوب برنامه Chromecast آشنا شوید. این راهنما فرض می‌کند که شما با مفاهیم پایه گیرنده CAF، مانند رهگیرهای پیام و mediaInformation آشنا هستید و با استفاده از ابزار Cast Command and Control، برای شبیه‌سازی فرستنده CAF آشنایی دارید.

برای استفاده از «ارائه دسته آگهی IMA DAI»، باید با شریک «ارائه دسته آگهی» کار کنید و باید حساب Ad Manager 360 Advanced داشته باشید. اگر حساب Ad Manager دارید، برای جزئیات بیشتر با مدیر حسابتان تماس بگیرید. برای کسب اطلاعات درباره ثبت‌نام در Ad Manager، به مرکز راهنمایی Ad Manager بروید.

برای اطلاعات درباره ادغام با پلاتفرم‌های دیگر، یا درباره استفاده از کیت‌های توسعه نرم‌افزار IMA سمت کارخواه، به کیت‌های توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی مراجعه کنید.

نمای کلی «ارائه پاد درج آگهی پویا» در IMA

پیاده‌سازی Pod Serving بااستفاده از IMA CAF DAI SDK شامل دو مؤلفه اصلی است، که در این راهنما نشان داده شده است:

  • StreamRequest: شیئی که درخواست جاری‌سازی به سرورهای تبلیغاتی Google را تعریف می‌کند. درخواست‌ها «کد شبکه»، «کلید دارایی سفارشی»، و کلید میانای برنامه‌سازی کاربردی اختیاری، و همچنین پارامترهای اختیاری دیگر را مشخص می‌کنند.
  • StreamManager: شیئی که ارتباط بین جاری‌سازی ویدیو و IMA DAI SDK را مدیریت می‌کند، مانند ارسال پینگ‌های ردیابی و ارسال رویدادهای جاری‌سازی به ناشر.

پیش‌نیازها

  • حساب کنسول توسعه‌دهنده Cast با دستگاه‌های آزمایشی ثبت‌شده.
  • یک برنامه گیرنده وب میزبانی‌شده که در «کنسول توسعه‌دهنده Cast» شما ثبت شده است و می‌توان آن را برای میزبانی کد ارائه‌شده توسط این راهنما اصلاح کرد.
  • برنامه ارسال‌کننده‌ای که برای استفاده از برنامه گیرنده وب شما پیکربندی شده است. برای اهداف این مثال، از ابزار فرمان و کنترل Cast به‌عنوان ارسال‌کننده خود استفاده کنید.

پیکربندی اشیای MediaInfo فرستنده

ابتدا، شیء MediaInfo برنامه فرستنده را پیکربندی کنید تا فیلدهای زیر را دربرگیرد:

فیلد محتوا
contentId شناسه یکتا برای این فایل رسانه‌ای.

CONTENT_ID

contentUrl اختیاری. نشانی وب جاری‌سازی پشتیبان برای پخش درصورت بار نشدن جاری‌سازی DAI.

BACKUP_STREAM_URL

contentType اختیاری. نوع Mime مربوط به جریان‌های پشتیبان‌گیری محتوا. فقط برای جاری‌سازی‌های DASH لازم است.

CONTENT_STREAM_MIMETYPE

streamType رشته ثابت یا تحت‌اللفظی استفاده‌شده برای این مقدار بسته به پلاتفرم فرستنده متفاوت است.
customData فیلد customData حاوی ذخیره مقدار کلید فیلدهای الزامی دیگر است. در این نمونه، پارامترهای جاری‌سازی DAI شما وجود دارد. در برنامه تولید، ممکن است درعوض شناسه‌ای را ارسال کنید که برنامه گیرنده ارسال محتوای شما از آن برای بازیابی این پارامترها با درخواست سمت سرور استفاده می‌کند.
فیلد محتوا
daiStreamType نوع جاری‌سازی DAI شما. یکی از "LIVE" یا "VOD"

DAI_STREAM_TYPE

networkCode کد شبکه برای حساب Google Ad Manager 360 شما.

NETWORK_CODE

customAssetKey این فیلد فقط برای جاری‌سازی‌های زنده لازم است. کلید دارایی سفارشی که رویداد «ارائه پاد» شما را در Google Ad Manager 360 شناسایی می‌کند.

CUSTOM_ASSET_KEY

apiKey کلید میانای برنامه‌سازی کاربردی اختیاری برای بازیابی شناسه جاری‌سازی از IMA DAI SDK.

API_KEY

در اینجا چند نمونه کد برای کمک به شروع کار آورده شده است:

وب

برای پیکربندی این مقادیر در فرستنده وب Cast، ابتدا یک شیء MediaInfo با داده‌های موردنیاز ایجاد کنید، سپس یک درخواست بارگیری به گیرنده وب ارسال کنید.

// Create mediaInfo object
const mediaInfo = new chrome.cast.media.MediaInfo("CONTENT_ID");
mediaInfo.contentUrl = "BACKUP_STREAM_URL";
mediaInfo.contentType = "CONTENT_STREAM_MIMETYPE";
mediaInfo.streamType = chrome.cast.media.StreamType.LIVE;
mediaInfo.customData = {
  daiStreamType: "DAI_STREAM_TYPE",
  networkCode: "NETWORK-CODE",
  customAssetKey: "CUSTOM_ASSET_KEY",
  apiKey: "API_KEY"
};

// Make load request to cast web receiver
const castSession = cast.framework.CastContext.getInstance().getCurrentSession();
const request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
  () => { console.log('Load succeed'); },
  (errorCode) => { console.log('Error code: ' + errorCode); });

Android

برای پیکربندی این مقادیر در فرستنده وب Cast، ابتدا یک شیء MediaInfo با داده‌های موردنیاز ایجاد کنید، سپس یک درخواست بارگیری به گیرنده وب ارسال کنید.

JSONObject customData = new JSONObject()?
  .put("daiStreamType", "DAI_STREAM_TYPE")
  .put("networkCode", "NETWORK-CODE")
  .put("customAssetKey", "CUSTOM_ASSET_KEY")
  .put("apiKey", "API_KEY");
MediaInfo mediaInfo = MediaInfo.Builder("CONTENT_ID")
  .setContentUrl("BACKUP_STREAM_URL")
  .setContentType("CONTENT_STREAM_MIMETYPE")
  .setStreamType(MediaInfo.STREAM_TYPE_LIVE)
  .setCustomData(customData)
  .build();

RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient();
remoteMediaClient.load(new MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build());

iOS (Obj-C)

برای پیکربندی این مقادیر در فرستنده وب Cast، ابتدا یک شیء GCKMediaInformation با داده‌های موردنیاز ایجاد کنید، سپس یک درخواست بارگیری به گیرنده وب ارسال کنید.

NSURL url = [NSURL URLWithString:@"BACKUP_STREAM_URL"];
NSDictionary *customData = @{
  @"daiStreamType": @"DAI_STREAM_TYPE",
  @"networkCode": @"NETWORK-CODE",
  @"customAssetKey": @"CUSTOM_ASSET_KEY",
  @"apiKey": @"API_KEY"};
mediaInfoBuilder.customData = customData;

GCKMediaInformationBuilder *mediaInfoBuilder =
  [[GCKMediaInformationBuilder alloc] initWithContentID: @"CONTENT_ID"];
mediaInfoBuilder.contentURL = url;
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE";
mediaInfoBuilder.streamType = GCKMediaStreamTypeLive;
mediaInfoBuilder.customData = customData;
self.mediaInformation = [mediaInfoBuilder build];

GCKRequest *request = [self.sessionManager.currentSession.remoteMediaClient loadMedia:self.mediaInformation];
if (request != nil) {
  request.delegate = self;
}

iOS (Swift)

برای پیکربندی این مقادیر در فرستنده وب Cast، ابتدا یک شیء GCKMediaInformation با داده‌های موردنیاز ایجاد کنید، سپس یک درخواست بارگیری به گیرنده وب ارسال کنید.

let url = URL.init(string: "BACKUP_STREAM_URL")
guard let mediaURL = url else {
  print("invalid mediaURL")
  return
}

let customData = [
  "daiStreamType": "DAI_STREAM_TYPE",
  "networkCode": "NETWORK-CODE",
  "customAssetKey": "CUSTOM_ASSET_KEY",
  "region": "API_KEY"
]

let mediaInfoBuilder = GCKMediaInformationBuilder.init(contentId: "CONTENT_ID")
mediaInfoBuilder.contentURL = mediaUrl
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE"
mediaInfoBuilder.streamType = GCKMediaStreamType.Live
mediaInfoBuilder.customData = customData
mediaInformation = mediaInfoBuilder.build()

guard let mediaInfo = mediaInformation else {
  print("invalid mediaInformation")
  return
}

if let request = sessionManager.currentSession?.remoteMediaClient?.loadMedia
(mediaInfo) {
  request.delegate = self
}

ابزار CAC

برای پیکربندی این مقادیر در ابزار Cast Command and Control، روی برگه Load Media کلیک کنید و نوع درخواست بارگذاری سفارشی را روی LOAD تنظیم کنید. سپس داده‌های JSON را در کادر نوشتار با این JSON جایگزین کنید:

{
  "media": {
    "contentId": "CONTENT_ID",
    "contentUrl": "BACKUP_STREAM_URL",
    "contentType": ""CONTENT_STREAM_MIMETYPE"",
    "streamType": "LIVE",
    "customData": {
      "daiStreamType": "DAI_STREAM_TYPE",
      "networkCode": "NETWORK-CODE",
      "customAssetKey": "CUSTOM_ASSET_KEY",
      "oAuthToken": "API_KEY"
    }
  }
}

این درخواست بارگیری سفارشی را می‌توان به گیرنده ارسال کرد تا بقیه مراحل را آزمایش کند.

ایجاد گیرنده CAF پایه

یک گیرنده وب سفارشی ایجاد کنید، همانطور که در راهنمای گیرنده وب سفارشی CAF SDK دیده می‌شود.

کد گیرنده شما باید به این شکل باشد:

<html>
<head>
  <script
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
  </script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    // ...
  </script>
</body>
</html>

کیت توسعه نرم‌افزار IMA DAI را وارد کنید و Player Manager را دریافت کنید

یک برچسب دستورگان برای وارد کردن IMA DAI SDK برای CAF به گیرنده وب خود اضافه کنید، درست بعداز بارگیری دستورگان CAF. در برچسب دستورگان، بافت گیرنده و مدیر پخش‌کننده را قبل‌از شروع گیرنده به‌عنوان ثابت ذخیره کنید.

<html>
<head>
  <script
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();

    castContext.start();
  </script>
</body>
</html>

مقداردهی اولیه IMA Stream Manager

«مدیر جریان IMA» را مقداردهی اولیه کنید.

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    castContext.start();
  </script>
</body>
</html>

ایجاد رهگیر بارگذاری مدیر جریان

قبل‌از اینکه موارد رسانه‌ای شما به CAF منتقل شود، درخواست جاری‌سازی خود را در رهگیر پیام LOAD ایجاد کنید.

    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    /**
     * Creates a livestream request object for a Pod Serving stream.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {StreamRequest} an IMA stream request
     */
    const createStreamRequest = (castRequest) => { /* ... */};

    /**
     * Initates a DAI stream request for the final stream manifest.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
     */
    const createDAICastRequest = (castRequest) => {
        return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
          .then((castRequestWithPodStreamData) => {
            console.log('Successfully made DAI stream request.');
            // ...
            return castRequestWithPodStreamData;
          })
          .catch((error) => {
            console.log('Failed to make DAI stream request.');
            // CAF will automatically fallback to the content URL
            // that it can read from the castRequest object.
            return castRequest;
          });
    };

    playerManager.setMessageInterceptor(
        cast.framework.messages.MessageType.LOAD, createDAICastRequest);

    castContext.start();

ایجاد درخواست جاری‌سازی

تابع createStreamRequest را برای ایجاد جاری‌سازی «ارائه Pod» براساس درخواست بارگذاری CAF تکمیل کنید.

    /**
     * Creates a livestream request object for a Pod Serving stream.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {StreamRequest} an IMA stream request
     */
    const createStreamRequest = (castRequest) => {
      const customData = castRequest.media.customData;
      let streamRequest;
      if (customData.daiStreamType == "LIVE") {
        streamRequest = new google.ima.cast.dai.api.PodStreamRequest();
        streamRequest.customAssetKey = customData.customAssetKey;
        streamRequest.networkCode = customData.networkCode;
        streamRequest.apiKey = customData.apiKey;
      } else if (customData.daiStreamType == "VOD") {
        streamRequest = new google.ima.cast.dai.api.PodVodStreamRequest();
        streamRequest.networkCode = customData.networkCode;
        streamRequest.apiKey = customData.apiKey;
      }
      return streamRequest;
    };

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

اگر درخواست جاری‌سازی شما موفقیت‌آمیز بود، از streamManager.getStreamId() برای بازیابی شناسه جاری‌سازی استفاده کنید. «شریک فنی ویدیو» (VTP) یا دستکاری‌کننده مانیفست سفارشی شما دستورالعمل‌هایی را برای بازیابی نشانی وب مانیفست بااستفاده از این شناسه جاری‌سازی ارائه خواهد کرد.

وقتی نشانی وب مانیفست خود را بازیابی کردید، contentUrl موجود را با manifestUrl جدید جایگزین کنید.

درنهایت، قبل‌از برگرداندن مانیفست جریان اصلاح‌شده، روش loadStreamMetadata را در streamManager خود فراخوانی کنید تا به IMA SDK اطلاع دهید که می‌تواند به‌طور ایمن فراداده جریان را درخواست کند. این فراخوانی فقط برای جاری‌سازی‌های VOD لازم است.

    /**
     * Initates a DAI stream request for the final stream manifest.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
     */
    const createDAICastRequest = (castRequest) => {
        return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
          .then((castRequestWithPodStreamData) => {
            console.log('Successfully made DAI stream request.');

            // This is a sample VTP integration. Consult your VTP documentation
            // for how to retrieve an ad-stitched stream manifest URL.
            const manifestTemplate = "https://.../manifest.m3u8?gam_stream_id=[[STREAMID]]";
            const streamId = streamManager.getStreamId();
            const manifestUrl = manifestTemplate.replace('[[STREAMID]]', streamId)
            // Assign your manifestUrl to the request's content URL.
            castRequestWithPodStreamData.media.contentUrl = manifestUrl;

            // After generating the manifest URL, VOD streams must notify the
            // IMA SDK that it is safe to request ad pod metadata.
            // This is only necessary for VOD streams. It is a no-op for
            // livestreams, so no conditional is needed.
            streamManager.loadStreamMetadata();

            return castRequestWithPodStreamData;
          })
          .catch((error) => {
            console.log('Failed to make DAI stream request.');
            // CAF will automatically fallback to the content URL
            // that it can read from the castRequest object.
            return castRequest;
          });
    };

پاک‌سازی دارایی‌های IMA DAI

وقتی درخواست و نمایش آگهی‌ها را در یک Pod Serving stream با IMA DAI SDK با موفقیت به پایان رساندید، پیشنهاد می‌کنیم پس‌از تکمیل جلسه Pod Serving، منابع را پاک کنید. برای توقف بازپخش جاری‌سازی، توقف همه ردگیری‌های آگهی، و واگذاری همه دارایی‌های جاری‌سازی بارشده، StreamManager.destroy() را فراخوانی کنید.