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

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

راهکار «درج آگهی پویا» موردنظرتان را انتخاب کنید

DAI ارائه‌دهنده Pod

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

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

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

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

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

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

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

نمای کلی ارائه واحد IMA DAI

پیاده‌سازی «ارائه واحد تبلیغات» بااستفاده از «کیت توسعه نرم‌افزار IMA CAF DAI» شامل دو جزء اصلی است که در این راهنما نشان داده شده است:

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

پیش‌نیازها

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

پیکربندی کردن اشیای 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 کلید اختیاری API برای بازیابی «شناسه جاری‌سازی» از «کیت توسعه نرم‌افزار IMA DAI».

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

برای پیکربندی این مقادیر در ابزار فرمان و کنترل پخش محتوا، روی برگه «بار کردن رسانه» کلیک کنید و نوع درخواست بار سفارشی را روی 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 را وارد کنید و «مدیر پخش‌کننده» را دریافت کنید

برچسبی برای وارد کردن «کیت توسعه نرم‌افزار IMA DAI برای 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>

ایجاد رهگیر بار مدیر جاری‌سازی

قبل‌از اینکه موارد رسانه‌ای شما به 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();

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

برای ایجاد جاری‌سازی «خدمات‌دهی واحد» براساس درخواست بار CAF، تابع createStreamRequest را تکمیل کنید.

    /**
     * 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

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