الإعداد باستخدام "إدراج الإعلان الديناميكي" (DAI) مع الخدمة الكاملة

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

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

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

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

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

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

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

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

يوفّر نموذج التطبيق مشغّل فيديو يعمل على تشغيل فيديو HLS. استخدِم هذا كبداية لدمج إمكانات IMA DAI في حزمة تطوير البرامج (SDK) لتقنية IMA DAI.

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

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

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

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

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

لا يحتوي مشغّل الفيديو النموذجي على أي رمز دمج لحزمة تطوير البرامج (SDK) الخاصة بتقنية IMA DAI حتى الآن. يتكوّن نموذج التطبيق من جزأين رئيسيين:

  1. ‫samplevideoplayer/SampleVideoPlayer.java: مشغّل HLS مستند إلى ExoPlayer يُستخدَم كأساس لدمج IMA DAI.

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

إضافة حزمة تطوير البرامج (SDK) لتقنية IMA DAI إلى تطبيق المشغّل

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

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.11.0"
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.21"))
    implementation("androidx.appcompat:appcompat:1.8.0")
    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.40.0")
}

دمج حزمة تطوير البرامج (SDK) لتقنية 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());
  }

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

    للعمل مع ميزة "إدراج الإعلان الديناميكي"، يجب أن يمرّر المشغّل أحداث ID3 إلى حزمة تطوير البرامج (SDK) لميزة "إدراج الإعلان الديناميكي" في "إعلانات الوسائط التفاعلية". تؤدي الطريقة 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);
      }
    }
  };
}

  3. أضِف طريقة buildStreamRequest() لإنشاء SteamRequest. تتيح هذه الطريقة التبديل بين أحداث البث المختلفة بناءً على كيفية ضبط المتغيّر CONTENT_TYPE. البث التلقائي المستخدَم في هذا الدليل هو بث نموذج فيديو عند الطلب (VOD) عبر بروتوكول 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;
}

  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());
    }
  };
}

  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;
}

  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);
  }
}

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

    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);
  }

  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;
}

  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>

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

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

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

إذا استمرّت المشاكل، يُرجى الانتقال إلى منتدى حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK).