إعداد حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لعرض الإعلانات أثناء التشغيل

اختيار النظام الأساسي: HTML5 Android iOS tvOS Cast Roku

تسهّل حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك. يمكن لحِزم تطوير البرامج لإعلانات الوسائط التفاعلية طلب الإعلانات من أي خادم إعلانات متوافق مع VAST وإدارة تشغيل الإعلانات في تطبيقاتك. باستخدام حِزم تطوير البرامج لإدراج الإعلانات الديناميكي في "إعلانات الوسائط التفاعلية"، تقدّم التطبيقات طلب بث لإعلان وفيديو محتوى، سواء كان فيديو عند الطلب أو محتوى مباشر. بعد ذلك، تعرض حزمة SDK بث فيديو مدمجًا، ما يغنيك عن إدارة التبديل بين الفيديو الإعلاني وفيديو المحتوى داخل تطبيقك.

اختيار حلّ "إدخال الإعلانات الديناميكي" الذي يهمّك

الخدمة الكاملة عرض الإعلانات ضمن حزمة

إدراج إعلان ديناميكي شامل

يوضّح هذا الدليل كيفية دمج حزمة تطوير البرامج (SDK) الخاصة بـ "إعلانات الوسائط التفاعلية" (IMA) في تطبيق بسيط لمشغّل فيديو. إذا أردت الاطّلاع على نموذج تكامل مكتمل أو اتّباعه، يمكنك تنزيل BasicExample من GitHub.

ملاحظة: تتوافق حزمة IMA DAI SDK لنظام التشغيل Android مع كلّ من بث HLS وبث DASH.

يوضّح هذا الدليل كيفية ضبط ExoPlayer وحزمة تطوير البرامج (SDK) الخاصة بـ "إعلانات الوسائط التفاعلية" (IMA) لدمج الإعلانات الديناميكية (DAI) من أجل تشغيل بث مباشر وفق بروتوكول HTTP ‏(HLS). للاطّلاع على مثال على مشغّل فيديو يتيح بث محتوى HLS وDASH، يُرجى مراجعة المثال المتقدّم.

لاستخدام IMA DAI، يجب أن يكون لديك حساب على مدير الإعلانات 360 المتقدّم. إذا كان لديك حساب على "مدير إعلانات Google"، تواصَل مع مدير حسابك للحصول على مزيد من التفاصيل. للحصول على معلومات حول الاشتراك في "إدارة إعلانات Google"، يُرجى الانتقال إلى مركز مساعدة "إدارة إعلانات Google".

نقطة أساسية: يوفّر إضافة ExoPlayer لإعلانات الوسائط التفاعلية طريقة مبسطة لاستخدام ميزة "إدراج الإعلان الديناميكي" في "إعلانات الوسائط التفاعلية" على Android. لمزيد من التفاصيل، يُرجى الاطّلاع على دليل إضافة ExoPlayer IMA وExoPlayerExample على GitHub.

ملاحظة: للحصول على معلومات حول الدمج مع منصات أخرى أو استخدام حِزم تطوير البرامج (SDK) من جهة العميل في "إعلانات الوسائط التفاعلية"، يُرجى الاطّلاع على حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية.

نظرة عامة على IMA DAI

يتضمّن تنفيذ "إعلانات البث المباشر" في "إعلانات الوسائط التفاعلية" أربعة مكوّنات رئيسية في حزمة SDK كما هو موضّح في هذا الدليل:

• StreamDisplayContainer: هو عنصر حاوٍ يقع في أعلى عنصر تشغيل الفيديو ويحتوي على عناصر واجهة مستخدم الإعلان.
• ‫ AdsLoader: كائن يطلب عمليات بث ويتعامل مع الأحداث التي يتم تشغيلها بواسطة كائنات الرد على طلب البث. يجب إنشاء مثيل واحد فقط لأداة تحميل الإعلانات، ويمكن إعادة استخدامه طوال مدة تشغيل التطبيق.
• ‫ StreamRequest: كائن يحدّد طلب بث. يمكن أن تكون طلبات البث المباشر لفيديوهات عند الطلب أو أحداث بث مباشر. تحدّد طلبات البث المباشر مفتاح مادة عرض، بينما تحدّد طلبات الفيديو عند الطلب معرّفًا في "نظام إدارة المحتوى" ومعرّف فيديو. يمكن أن يتضمّن كلا نوعَي الطلبات اختياريًا مفتاح واجهة برمجة التطبيقات اللازم للوصول إلى عمليات البث المحدّدة، ورمز شبكة "مدير إعلانات Google" لكي تتعامل أداة تطوير البرامج لإعلانات الوسائط التفاعلية من Google مع معرّفات الإعلانات على النحو المحدّد في إعدادات "مدير إعلانات Google".
• ‫ StreamManager: عنصر يعالج عمليات بث "إدراج الإعلان الديناميكي" والتفاعلات مع الخلفية البرمجية لميزة "إدراج الإعلان الديناميكي". يتولّى مدير البث أيضًا معالجة طلبات تتبُّع ping وإعادة توجيه أحداث البث والإعلانات إلى الناشر.

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

• استوديو Android
• تطبيق مشغّل فيديو نموذجي لدمج حزمة تطوير البرامج (SDK)

تنزيل تطبيق مشغّل الفيديو النموذجي وتشغيله

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

1. نزِّل تطبيق مشغّل الفيديو التجريبي وفكّ ضغطه.

2. ابدأ تشغيل "استوديو Android" وانقر على فتح مشروع حالي في "استوديو Android"، أو إذا كان "استوديو Android" قيد التشغيل، انقر على ملف > جديد > استيراد مشروع. بعد ذلك، انقر على SampleVideoPlayer/build.gradle.

3. أجرِ عملية مزامنة Gradle من خلال النقر على أدوات > Android > مزامنة المشروع مع ملفات Gradle.

4. تأكَّد من أنّ تطبيق المشغّل يتم تجميعه وتشغيله على جهاز Android فعلي أو جهاز Android افتراضي باستخدام تشغيل > تشغيل "التطبيق". من الطبيعي أن يستغرق تحميل بث الفيديو بضع ثوانٍ قبل تشغيله.

ملاحظة: إذا كنت جديدًا في مجال تطوير تطبيقات Android، يمكنك الاطّلاع على البرامج التعليمية حول تصحيح الأخطاء عبر USB واستخدام الأجهزة الافتراضية. يجب تنفيذ أحد هذين الإجراءين لتشغيل تطبيقك الجديد والاطّلاع على شكله.

فحص مشغّل الفيديو النموذجي

لا يحتوي مشغّل الفيديو النموذجي على أي رمز دمج لحزمة تطوير البرامج الخاصة بـ "الإعلانات الديناميكية أثناء عرض الفيديو" حتى الآن. يتألف التطبيق النموذجي من جزأين رئيسيَّين:

1. samplevideoplayer/SampleVideoPlayer.java: مشغّل HLS يستند إلى ExoPlayer ويشكّل الأساس لدمج "الإعلانات الديناميكية أثناء البث" من "إعلانات الوسائط التفاعلية".

2. ‫videoplayerapp/MyActivity.java: ينشئ هذا النشاط مشغّل الفيديو ويمرّر إليه Context وmedia3.ui.PlayerView.

إضافة حزمة تطوير البرامج (SDK) الخاصة بـ "الإعلانات الديناميكية أثناء البث" من "الإعلانات التفاعلية" إلى تطبيق المشغّل

يجب أيضًا تضمين إشارة إلى حزمة تطوير البرامج لإعلانات الوسائط التفاعلية (IMA) الخاصة بالإدراج الديناميكي للإعلانات (DAI). في "استوديو Android"، أضِف ما يلي إلى ملف build.gradle على مستوى التطبيق، والذي يقع في app/build.gradle. تتطلّب حزمة تطوير البرامج لإعلانات الوسائط التفاعلية تفعيل ميزة إزالة التشويش في المكتبة، ويجب إجراء ذلك من خلال ضبط coreLibraryDesugaringEnabled true وإضافة 'com.android.tools:desugar_jdk_libs' كملحق في ملف build.gradle. لمزيد من التفاصيل، يُرجى الاطّلاع على واجهات برمجة تطبيقات Java 11 والإصدارات الأحدث المتاحة من خلال إزالة التشفير باستخدام مواصفات nio.

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.9.1"
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.0"))
    implementation("androidx.appcompat:appcompat:1.7.1")
    implementation("androidx.media3:media3-ui:$media3_version")
    implementation("androidx.media3:media3-exoplayer:$media3_version")
    implementation("androidx.media3:media3-exoplayer-hls:$media3_version")
    implementation("androidx.media3:media3-exoplayer-dash:$media3_version")
    implementation("androidx.mediarouter:mediarouter:1.8.1")
    implementation("com.google.ads.interactivemedia.v3:interactivemedia:3.39.0")
}
build.gradle

ملاحظة مهمة: من المفترض أن يتم تجميع تطبيقك وتشغيله في هذه المرحلة، على الرغم من أنّك لم تضِف بعد عناصر واجهة المستخدم أو الرمز البرمجي لطلب الإعلانات وعرضها.

دمج "حزمة تطوير البرامج للإعلانات التفاعلية" (IMA) الخاصة بـ "الإعلانات الديناميكية أثناء البث" (DAI)

1. أنشئ فئة جديدة باسم SampleAdsWrapper في الحزمة videoplayerapp (في app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) لتضمين SampleVideoPlayer الحالي وإضافة منطق لتنفيذ IMA DAI. لإجراء ذلك، يجب أولاً إنشاء AdsLoader يُستخدَم لطلب بث "إدراج الإعلان الديناميكي".

   يتضمّن هذا المقتطف مَعلمات نموذجية لبروتوكول HLS وDASH، ولأحداث البث المباشر والفيديوهات المتوفرة عند الطلب. لضبط مصدر البيانات الذي يتم تشغيله، عدِّل المتغيّر CONTENT_TYPE ‎.

   package com.google.ads.interactivemedia.v3.samples.videoplayerapp;
   
   import android.annotation.SuppressLint;
   import android.content.Context;
   import android.view.ViewGroup;
   import android.webkit.WebView;
   import androidx.annotation.Nullable;
   import com.google.ads.interactivemedia.v3.api.AdErrorEvent;
   import com.google.ads.interactivemedia.v3.api.AdEvent;
   import com.google.ads.interactivemedia.v3.api.AdsLoader;
   import com.google.ads.interactivemedia.v3.api.AdsManagerLoadedEvent;
   import com.google.ads.interactivemedia.v3.api.CuePoint;
   import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
   import com.google.ads.interactivemedia.v3.api.StreamDisplayContainer;
   import com.google.ads.interactivemedia.v3.api.StreamManager;
   import com.google.ads.interactivemedia.v3.api.StreamRequest;
   import com.google.ads.interactivemedia.v3.api.StreamRequest.StreamFormat;
   import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate;
   import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer;
   import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
   import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer.SampleVideoPlayerCallback;
   import java.util.ArrayList;
   import java.util.HashMap;
   import java.util.List;
   
   /** This class adds ad-serving support to Sample HlsVideoPlayer */
   @SuppressLint("UnsafeOptInUsageError")
   /* @SuppressLint is needed for new media3 APIs. */
   public class SampleAdsWrapper
       implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {
   
     // Live HLS stream asset key.
     private static final String TEST_HLS_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
   
     // Live DASH stream asset key.
     private static final String TEST_DASH_ASSET_KEY = "PSzZMzAkSXCmlJOWDmRj8Q";
   
     // VOD HLS content source and video IDs.
     private static final String TEST_HLS_CONTENT_SOURCE_ID = "2548831";
     private static final String TEST_HLS_VIDEO_ID = "tears-of-steel";
   
     // VOD DASH content source and video IDs.
     private static final String TEST_DASH_CONTENT_SOURCE_ID = "2559737";
     private static final String TEST_DASH_VIDEO_ID = "tos-dash";
   
     private static final String NETWORK_CODE = "21775744923";
   
     private static final String PLAYER_TYPE = "DAISamplePlayer";
   
     private enum ContentType {
       LIVE_HLS,
       LIVE_DASH,
       VOD_HLS,
       VOD_DASH,
     }
   
     // Set CONTENT_TYPE to the associated enum for the stream type you would like to test.
     private static final ContentType CONTENT_TYPE = ContentType.VOD_HLS;
   
     /** Log interface, so we can output the log commands to the UI or similar. */
     public interface Logger {
       void log(String logMessage);
     }
   
     private final ImaSdkFactory sdkFactory;
     private AdsLoader adsLoader;
     private StreamManager streamManager;
     private final List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks;
   
     private final SampleVideoPlayer videoPlayer;
     private final Context context;
     private final ViewGroup adUiContainer;
   
     private String fallbackUrl;
     private Logger logger;
   
     /**
      * Creates a new SampleAdsWrapper that implements IMA direct-ad-insertion.
      *
      * @param context the app's context.
      * @param videoPlayer underlying HLS video player.
      * @param adUiContainer ViewGroup in which to display the ad's UI.
      */
     public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer, ViewGroup adUiContainer) {
       this.videoPlayer = videoPlayer;
       this.context = context;
       this.adUiContainer = adUiContainer;
       sdkFactory = ImaSdkFactory.getInstance();
       playerCallbacks = new ArrayList<>();
       createAdsLoader();
     }
   
     private void enableWebViewDebugging() {
       WebView.setWebContentsDebuggingEnabled(true);
     }
   
     private void createAdsLoader() {
       enableWebViewDebugging();
       VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer();
       StreamDisplayContainer displayContainer =
           ImaSdkFactory.createStreamDisplayContainer(adUiContainer, videoStreamPlayer);
       videoPlayer.setSampleVideoPlayerCallback(createSampleVideoPlayerCallback());
       adsLoader =
           sdkFactory.createAdsLoader(context, MyActivity.getImaSdkSettings(), displayContainer);
     }
   
     public void requestAndPlayAds() {
       adsLoader.addAdErrorListener(this);
       adsLoader.addAdsLoadedListener(this);
       adsLoader.requestStream(buildStreamRequest());
     }
   SampleAdsWrapper.java

2. أنشئ طريقة مساعدة createSampleVideoPlayerCallback() للتعامل مع إنشاء مثيل واجهة SampleVideoPlayerCallback الذي يوسّع VideoStreamPlayer.VideoStreamPlayerCallback.

   لكي يعمل مشغّل الفيديو مع ميزة "الإعلانات الديناميكية أثناء عرض الفيديو"، يجب أن ينقل أحداث ID3 إلى حزمة تطوير البرامج الخاصة بميزة "الإعلانات الديناميكية أثناء عرض الفيديو" من "إعلانات الوسائط التفاعلية". تنفّذ الطريقة callback.onUserTextReceived() هذه العملية، كما هو موضّح في نموذج الرمز البرمجي التالي.

   private SampleVideoPlayerCallback createSampleVideoPlayerCallback() {
     return new SampleVideoPlayerCallback() {
       @Override
       public void onUserTextReceived(String userText) {
         for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
           callback.onUserTextReceived(userText);
         }
       }
   
       @Override
       public void onSeek(int windowIndex, long positionMs) {
         // See if we would seek past an ad, and if so, jump back to it.
         long newSeekPositionMs = positionMs;
         if (streamManager != null) {
           CuePoint prevCuePoint = streamManager.getPreviousCuePointForStreamTimeMs(positionMs);
           if (prevCuePoint != null && !prevCuePoint.isPlayed()) {
             newSeekPositionMs = prevCuePoint.getStartTimeMs();
           }
         }
         videoPlayer.seekTo(windowIndex, newSeekPositionMs);
       }
   
       @Override
       public void onContentComplete() {
         for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
           callback.onContentComplete();
         }
       }
   
       @Override
       public void onPause() {
         for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
           callback.onPause();
         }
       }
   
       @Override
       public void onResume() {
         for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
           callback.onResume();
         }
       }
   
       @Override
       public void onVolumeChanged(int percentage) {
         for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
           callback.onVolumeChanged(percentage);
         }
       }
     };
   }
   SampleAdsWrapper.java

3. أضِف طريقة buildStreamRequest() لإنشاء SteamRequest. تتيح هذه الطريقة التبديل بين تدفقات مختلفة استنادًا إلى طريقة ضبط المتغيّر CONTENT_TYPE. إنّ البث التلقائي المستخدَم في هذا الدليل هو بث HLS لعيّنة فيديو عند الطلب من IMA.

   @Nullable
   private StreamRequest buildStreamRequest() {
     StreamRequest request;
     switch (CONTENT_TYPE) {
       case LIVE_HLS:
         // Live HLS stream request.
         return sdkFactory.createLiveStreamRequest(TEST_HLS_ASSET_KEY, null, NETWORK_CODE);
       case LIVE_DASH:
         // Live DASH stream request.
         return sdkFactory.createLiveStreamRequest(TEST_DASH_ASSET_KEY, null, NETWORK_CODE);
       case VOD_HLS:
         // VOD HLS request.
         request =
             sdkFactory.createVodStreamRequest(
                 TEST_HLS_CONTENT_SOURCE_ID, TEST_HLS_VIDEO_ID, null, NETWORK_CODE);
         request.setFormat(StreamFormat.HLS);
         return request;
       case VOD_DASH:
         // VOD DASH request.
         request =
             sdkFactory.createVodStreamRequest(
                 TEST_DASH_CONTENT_SOURCE_ID, TEST_DASH_VIDEO_ID, null, NETWORK_CODE);
         request.setFormat(StreamFormat.DASH);
         return request;
     }
     // Content type not selected.
     return null;
   }
   SampleAdsWrapper.java

4. تحتاج أيضًا إلى VideoStreamPlayer لتشغيل البث، لذا أضِف طريقة createVideoStreamPlayer()، والتي تنشئ فئة مجهولة الهوية تنفّذ VideoStreamPlayer.

   private VideoStreamPlayer createVideoStreamPlayer() {
     return new VideoStreamPlayer() {
       @Override
       public void loadUrl(String url, List<HashMap<String, String>> subtitles) {
         videoPlayer.setStreamUrl(url);
         videoPlayer.play();
       }
   
       @Override
       public void pause() {
         // Pause player.
         videoPlayer.pause();
       }
   
       @Override
       public void resume() {
         // Resume player.
         videoPlayer.play();
       }
   
       @Override
       public int getVolume() {
         // Make the video player play at the current device volume.
         return 100;
       }
   
       @Override
       public void addCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
         playerCallbacks.add(videoStreamPlayerCallback);
       }
   
       @Override
       public void removeCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
         playerCallbacks.remove(videoStreamPlayerCallback);
       }
   
       @Override
       public void onAdBreakStarted() {
         // Disable player controls.
         videoPlayer.enableControls(false);
         log("Ad Break Started\n");
       }
   
       @Override
       public void onAdBreakEnded() {
         // Re-enable player controls.
         if (videoPlayer != null) {
           videoPlayer.enableControls(true);
         }
         log("Ad Break Ended\n");
       }
   
       @Override
       public void onAdPeriodStarted() {
         log("Ad Period Started\n");
       }
   
       @Override
       public void onAdPeriodEnded() {
         log("Ad Period Ended\n");
       }
   
       @Override
       public void seek(long timeMs) {
         // An ad was skipped. Skip to the content time.
         videoPlayer.seekTo(timeMs);
         log("seek");
       }
   
       @Override
       public VideoProgressUpdate getContentProgress() {
         return new VideoProgressUpdate(
             videoPlayer.getCurrentPositionMs(), videoPlayer.getDuration());
       }
     };
   }
   SampleAdsWrapper.java

5. نفِّذ أدوات الاستماع المطلوبة وأضِف إمكانية معالجة الأخطاء.

   لاحظ تنفيذ AdErrorListener، لأنّه يستدعي عنوان URL احتياطيًا في حال تعذّر تشغيل الإعلانات. بما أنّ المحتوى والإعلانات مضمّنة في بث واحد، يجب أن تكون مستعدًا لطلب بث احتياطي في حال حدوث خطأ في بث "إدراج الإعلانات الديناميكي".

   /** AdErrorListener implementation */
   @Override
   public void onAdError(AdErrorEvent event) {
     log(String.format("Error: %s\n", event.getError().getMessage()));
     // play fallback URL.
     log("Playing fallback Url\n");
     videoPlayer.setStreamUrl(fallbackUrl);
     videoPlayer.enableControls(true);
     videoPlayer.play();
   }
   
   /** AdEventListener implementation */
   @Override
   public void onAdEvent(AdEvent event) {
     switch (event.getType()) {
       case AD_PROGRESS:
         // Do nothing or else log will be filled by these messages.
         break;
       default:
         log(String.format("Event: %s\n", event.getType()));
         break;
     }
   }
   
   /** AdsLoadedListener implementation */
   @Override
   public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
     streamManager = event.getStreamManager();
     streamManager.addAdErrorListener(this);
     streamManager.addAdEventListener(this);
     streamManager.init();
   }
   
   /** Sets fallback URL in case ads stream fails. */
   void setFallbackUrl(String url) {
     fallbackUrl = url;
   }
   SampleAdsWrapper.java

6. أضِف رمزًا لتسجيل الدخول.

   /** Sets logger for displaying events to screen. Optional. */
   void setLogger(Logger logger) {
     this.logger = logger;
   }
   
   private void log(String message) {
     if (logger != null) {
       logger.log(message);
     }
   }
   SampleAdsWrapper.java

7. عدِّل MyActivity في videoplayerapp لإنشاء واستدعاء SampleAdsWrapper. يجب أيضًا إجراء طلب إلى ImaSdkFactory.initialize() هنا باستخدام طريقة مساعدة لإنشاء مثيل ImaSdkSettings.

   ملاحظة مهمة: لتحسين أوقات تحميل IMA، استخدِم طريقة ImaSdkFactory.initialize() في أقرب وقت ممكن في دورة حياة التطبيق. يؤدي استدعاء الطريقة مبكرًا إلى زيادة الوقت المتاح لـ IMA لتحميل الموارد اللازمة قبل طلب البث الأول. يقبل استدعاء الطريقة ImaSdkFactory.initialize() مثيلاً من ImaSdkSettings. احرص على استخدام قيم الإعدادات نفسها هنا وعند إنشاء مثيل AdsLoader. يستخدم هذا المثال طريقة المساعدة getImaSdkSettings() لضمان تطابق قيم الإعدادات. لمزيد من المعلومات، يُرجى الاطّلاع على دليل تحسين وقت تحميل IMA>.
   package com.google.ads.interactivemedia.v3.samples.videoplayerapp;
   
   import android.annotation.SuppressLint;
   import android.app.Activity;
   import android.content.res.Configuration;
   import android.os.Bundle;
   import android.util.Log;
   import android.view.View;
   import android.widget.ImageButton;
   import android.widget.ScrollView;
   import android.widget.TextView;
   import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
   import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
   import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
   
   /** Main Activity that plays media using {@link SampleVideoPlayer}. */
   @SuppressLint("UnsafeOptInUsageError")
   /* @SuppressLint is needed for new media3 APIs. */
   public class MyActivity extends Activity {
   
     private static final String DEFAULT_STREAM_URL =
         "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";
     private static final String APP_LOG_TAG = "ImaDaiExample";
     private static final String PLAYER_TYPE = "DAISamplePlayer";
     private static ImaSdkSettings imaSdkSettings;
   
     protected SampleVideoPlayer sampleVideoPlayer;
     protected ImageButton playButton;
   
     private boolean contentHasStarted = false;
   
     @Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_my);
   
       // Initialize the IMA SDK as early as possible when the app starts. If your app already
       // overrides Application.onCreate(), call this method inside the onCreate() method.
       // https://developer.android.com/topic/performance/vitals/launch-time#app-creation
       ImaSdkFactory.getInstance().initialize(this, getImaSdkSettings());
   
       View rootView = findViewById(R.id.videoLayout);
       sampleVideoPlayer =
           new SampleVideoPlayer(rootView.getContext(), rootView.findViewById(R.id.playerView));
       sampleVideoPlayer.enableControls(false);
       playButton = rootView.findViewById(R.id.playButton);
       final SampleAdsWrapper sampleAdsWrapper =
           new SampleAdsWrapper(this, sampleVideoPlayer, rootView.findViewById(R.id.adUiContainer));
       sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL);
   
       final ScrollView scrollView = findViewById(R.id.logScroll);
       final TextView textView = findViewById(R.id.logText);
   
       sampleAdsWrapper.setLogger(
           logMessage -> {
             Log.i(APP_LOG_TAG, logMessage);
             if (textView != null) {
               textView.append(logMessage);
             }
             if (scrollView != null) {
               scrollView.post(() -> scrollView.fullScroll(View.FOCUS_DOWN));
             }
           });
   
       // Set up play button listener to play video then hide play button.
       playButton.setOnClickListener(
           view -> {
             if (contentHasStarted) {
               sampleVideoPlayer.play();
             } else {
               contentHasStarted = true;
               sampleVideoPlayer.enableControls(true);
               sampleAdsWrapper.requestAndPlayAds();
             }
             playButton.setVisibility(View.GONE);
           });
       orientVideoDescription(getResources().getConfiguration().orientation);
     }
   MyActivity.java

8. أضِف طريقة المساعد getImaSdkSettings() لإنشاء مثيل ImaSdkSettings.

   public static ImaSdkSettings getImaSdkSettings() {
     if (imaSdkSettings == null) {
       imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
       imaSdkSettings.setPlayerType(PLAYER_TYPE);
       // Set any additional IMA SDK settings here.
     }
     return imaSdkSettings;
   }
   MyActivity.java

9. عدِّل ملف تصميم النشاط activity_my.xml لإضافة عناصر واجهة المستخدم الخاصة بالتسجيل.

   <!-- UI element for viewing SDK event log -->
   <ScrollView
       android:id="@+id/logScroll"
       android:layout_width="match_parent"
       android:layout_height="0dp"
       android:layout_weight="0.5"
       android:padding="5dp"
       android:background="#DDDDDD">
   
       <TextView
           android:id="@+id/logText"
           android:layout_width="match_parent"
           android:layout_height="wrap_content">
       </TextView>
   </ScrollView>
   activity_my.xml

تهانينا! أنت الآن بصدد طلب إعلانات الفيديو وعرضها في تطبيق Android. ولتحسين عملية التنفيذ، راجِع الإشارات المرجعية وSnapback ومستندات واجهة برمجة التطبيقات.

تحديد المشاكل وحلّها

إذا كنت تواجه مشاكل في تشغيل إعلان فيديو، جرِّب تنزيل BasicExample المكتمل. إذا كان يعمل بشكل صحيح في BasicExample، من المحتمل أن تكون هناك مشكلة في رمز دمج "إعلانات الوسائط التفاعلية" في تطبيقك.

إذا استمرّت المشاكل، يُرجى الانتقال إلى منتدى IMA SDK.