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

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

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

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

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

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

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

برای استفاده از «ارائه دسته آگهی درج آگهی پویا IMA»، باید با شریک «ارائه دسته آگهی» کار کنید و حساب 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 شما وجود دارد. در برنامه تولید، ممکن است درعوض شناسه‌ای را ارسال کنید که برنامه گیرنده Cast شما از آن برای بازیابی این پارامترها با درخواست سمت سرور استفاده می‌کند.
فیلد محتوا
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 تنظیم کنید. سپس داده‌های 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 SDK و دریافت 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»

«مدیر جریان 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>

ایجاد Stream Manager Load Interceptor

قبل‌از اینکه موارد رسانه‌ای شما به 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 را تکمیل کنید تا براساس درخواست بارگذاری CAF، جاری‌سازی «ارائه Pod» ایجاد شود.

    /**
     * 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() را فراخوانی کنید.