כדי לדון במוצרים שלנו ולספק משוב, אפשר להצטרף לערוץ הרשמי של Ad Manager ב-Discord בשרת קהילת הפרסום והמדידה של Google.

תחילת העבודה עם תוסף IMA של ExoPlayer

‫ExoPlayer הוא נגן מדיה ל-Android. במדריך הזה נסביר איך להשתמש בתוסף ExoPlayer IMA. התוסף הזה משתמש ב-IMA DAI SDK כדי לשלוח בקשות לסטרימינג של מדיה ולהפעיל סטרימינג של מדיה עם מודעות ותוכן.

רשימת היתרונות של התוסף:

הוא מפשט את הקוד שנדרש לשילוב תכונות של IMA.
הפחתת הזמן שנדרש לעדכון לגרסאות חדשות של IMA.

התוסף ExoPlayer IMA תומך בפרוטוקולים של סטרימינג HLS ו-DASH. סיכום:

תמיכה בזרם של תוסף ExoPlayer-IMA
	שידור חי	שידורי VOD
HLS
DASH

‫ExoPlayer-IMA גרסה 1.1.0 ואילך תומכת בשידורים חיים ב-DASH.

במדריך הזה נעזרים במדריך ExoPlayer כדי ליצור אפליקציה מלאה ולשלב את התוסף. אפליקציה לדוגמה מלאה זמינה ב-ExoPlayerExample ב-GitHub.

דרישות מוקדמות

Android Studio
‫AndroidX Media3 ExoPlayer גרסה 1.0.0 ואילך לתמיכה ב-DAI.

יצירת פרויקט חדש ב-Android Studio

כדי ליצור פרויקט ב-Android Studio, פועלים לפי השלבים הבאים:

מפעילים את Android Studio.
בוחרים באפשרות Start a new Android Studio project (התחלת פרויקט חדש ב-Android Studio).
בדף בחירת הפרויקט, בוחרים בתבנית ללא פעילות.
לוחצים על הבא.
בדף Configure your project (הגדרת הפרויקט), נותנים שם לפרויקט ובוחרים באפשרות Java כשפה. הערה: IMA DAI SDK פועל עם Kotlin, אבל במדריך הזה יש דוגמאות ל-Java.

לוחצים על סיום.

הוספת התוסף ExoPlayer IMA לפרויקט

כדי להוסיף את תוסף IMA של ExoPlayer:

צריך לכלול את ההצהרות הבאות על ייבוא בקטע dependencies של קובץ build.gradle של האפליקציה:

dependencies {
    def media3_version = "1.8.0"
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.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"

    // The library adds the IMA ExoPlayer integration for ads.
    implementation "androidx.media3:media3-exoplayer-ima:$media3_version"
}build.gradle

מוסיפים את הרשאות המשתמש שנדרשות ל-IMA DAI SDK כדי לשלוח בקשות למודעות:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>AndroidManifest.xml

הגדרת ממשק המשתמש של ExoPlayer

כדי להגדיר את ממשק המשתמש של ExoPlayer:

יוצרים את אובייקט PlayerView עבור ExoPlayer.

משנים את התצוגה androidx.constraintlayout.widget.ConstraintLayout לתצוגה LinearLayout, כמומלץ על ידי תוסף ExoPlayer IMA:

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/container"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    tools:context=".MyActivity"
    tools:ignore="MergeRootFrame">

    <androidx.media3.ui.PlayerView
        android:id="@+id/player_view"
        android:fitsSystemWindows="true"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    <!-- UI element for viewing SDK event log -->
    <TextView
        android:id="@+id/logText"
        android:gravity="bottom"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:maxLines="100"
        android:scrollbars="vertical"
        android:textSize="@dimen/font_size">
    </TextView>

</LinearLayout>
activity_my.xml

הוספת פרמטרים לסטרימינג

בדף של דוגמאות לסטרימינג ב-IMA יש נכסי סטרימינג לדוגמה שאפשר להשתמש בהם כדי לבדוק את הפרויקט. כדי להגדיר סטרימינג משלכם, אפשר לעיין בקטע בנושא DAI ב-Ad Manager.

בשלב הזה מגדירים שידור חי. התוסף ExoPlayer IMA תומך גם בסטרימינג של VOD עם DAI. כדי לדעת אילו שינויים צריך לבצע באפליקציה כדי להפעיל שידורים של וידאו על פי דרישה (VOD), אפשר לעיין בשלב בנושא שידורים של וידאו על פי דרישה (VOD).

ייבוא התוסף ExoPlayer IMA

מוסיפים את הצהרות הייבוא הבאות לתוסף ExoPlayer:

import static androidx.media3.common.C.CONTENT_TYPE_HLS;

import android.annotation.SuppressLint;
import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import android.text.method.ScrollingMovementMethod;
import android.util.Log;
import android.widget.TextView;
import androidx.media3.common.MediaItem;
import androidx.media3.common.util.Util;
import androidx.media3.datasource.DataSource;
import androidx.media3.datasource.DefaultDataSource;
import androidx.media3.exoplayer.ExoPlayer;
import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionMediaSource;
import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionUriBuilder;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.ui.PlayerView;
import com.google.ads.interactivemedia.v3.api.AdEvent;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
import java.util.HashMap;
import java.util.Map;
MyActivity.java

ב-MyActivity.java, מוסיפים את המשתנים הפרטיים הבאים:
כדי לבדוק באמצעות סטרימינג HLS של Big Buck Bunny (Live), מוסיפים את מפתח הנכס שלו. אפשר למצוא עוד סטרימינג לבדיקה בדף הדוגמאות לסטרימינג של IMA.

יוצרים קבוע KEY_ADS_LOADER_STATE כדי לשמור ולאחזר את המצב AdsLoader:

/** Main Activity. */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class MyActivity extends Activity {

  private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
  private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
  private static final String LOG_TAG = "ImaExoPlayerExample";

  private PlayerView playerView;
  private TextView logText;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;
  private ImaSdkSettings imaSdkSettings;
MyActivity.java

יצירת מופע של `adsLoader`

מבטלים את השיטה onCreate. מחפשים את PlayerView ובודקים אם יש AdsLoader.State שמור. אפשר להשתמש במצב הזה כשמפעילים את האובייקט adsLoader.

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

  playerView = findViewById(R.id.player_view);

  // Checks if there is a saved AdsLoader state to be used later when initiating the AdsLoader.
  if (savedInstanceState != null) {
    Bundle adsLoaderStateBundle = savedInstanceState.getBundle(KEY_ADS_LOADER_STATE);
    if (adsLoaderStateBundle != null) {
      adsLoaderState =
          ImaServerSideAdInsertionMediaSource.AdsLoader.State.fromBundle(adsLoaderStateBundle);
    }
  }
}

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

חשוב: כדי לשפר את זמני הטעינה של IMA, צריך לקרוא לשיטה ImaSdkFactory.initialize() מוקדם ככל האפשר במחזור החיים של האפליקציה. הפעלת השיטה מוקדם ככל האפשר מאריכה את הזמן שנדרש ל-IMA לטעינת המשאבים הדרושים לפני הבקשה הראשונה לסטרימינג. הפעלת ה-method ImaSdkFactory.initialize() מקבלת מופע של ImaSdkSettings. חשוב להשתמש באותם ערכים של ההגדרות כאן וגם כשיוצרים מופע של AdsLoader. בדוגמה הזו נעשה שימוש בשיטת העזר getImaSdkSettings() כדי לוודא שערכי ההגדרות זהים. מידע נוסף זמין במאמר מדריך לאופטימיזציה של זמן הטעינה של IMA.

הוספת שיטות לאתחול הנגן

מוסיפים שיטה לאתחול הנגן. השיטה הזו צריכה לבצע את הפעולות הבאות:

יוצרים מכונת AdsLoader.
יוצרים את ExoPlayer.
יוצרים MediaItem באמצעות מפתח הנכס של השידור החי.
מגדירים את הערך MediaItem של הנגן.

// Create a server side ad insertion (SSAI) AdsLoader.
private ImaServerSideAdInsertionMediaSource.AdsLoader createAdsLoader() {
  ImaServerSideAdInsertionMediaSource.AdsLoader.Builder adsLoaderBuilder =
      new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(this, playerView);

  // Attempts to set the AdsLoader state if available from a previous session.
  if (adsLoaderState != null) {
    adsLoaderBuilder.setAdsLoaderState(adsLoaderState);
  }

  return adsLoaderBuilder
      .setAdEventListener(buildAdEventListener())
      .setImaSdkSettings(getImaSdkSettings())
      .build();
}

private void initializePlayer() {
  adsLoader = createAdsLoader();

  // Set up the factory for media sources, passing the ads loader.
  DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);

  DefaultMediaSourceFactory mediaSourceFactory = new DefaultMediaSourceFactory(dataSourceFactory);

  // MediaSource.Factory to create the ad sources for the current player.
  ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory =
      new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, mediaSourceFactory);

  // 'mediaSourceFactory' is an ExoPlayer component for the DefaultMediaSourceFactory.
  // 'adsMediaSourceFactory' is an ExoPlayer component for a MediaSource factory for IMA server
  // side inserted ad streams.
  mediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory);

  // Create a SimpleExoPlayer and set it as the player for content and ads.
  player = new ExoPlayer.Builder(this).setMediaSourceFactory(mediaSourceFactory).build();
  playerView.setPlayer(player);
  adsLoader.setPlayer(player);

  // Create the MediaItem to play, specifying the stream URI.
  Uri ssaiUri = buildLiveStreamUri(SAMPLE_ASSET_KEY, CONTENT_TYPE_HLS);
  MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiUri);

  // Prepare the content and ad to be played with the ExoPlayer.
  player.setMediaItem(ssaiMediaItem);
  player.prepare();

  // Set PlayWhenReady. If true, content and ads will autoplay.
  player.setPlayWhenReady(false);
}

/**
 * Builds an IMA SSAI live stream URI for the given asset key and format.
 *
 * @param assetKey The asset key of the live stream.
 * @param format The format of the live stream request, either {@code CONTENT_TYPE_HLS} or {@code
 *     CONTENT_TYPE_DASH}.
 * @return The URI of the live stream.
 */
public Uri buildLiveStreamUri(String assetKey, int format) {
  Map<String, String> adTagParams = new HashMap<String, String>();
  // Update the adTagParams map with any parameters.
  // For more information, see https://support.google.com/admanager/answer/7320899

  return new ImaServerSideAdInsertionUriBuilder()
      .setAssetKey(assetKey)
      .setFormat(format)
      .setAdTagParameters(adTagParams)
      .build();
}
MyActivity.java

הוספת שיטה לשחרור הנגן

מוסיפים שיטה לשחרור הנגן. השיטה הזו צריכה לבצע את הפעולות הבאות ברצף:

מגדירים את הפניות לנגן כ-null ומשחררים את המשאבים של הנגן.
משחררים את המצב adsLoader.

private void releasePlayer() {
  // Set the player references to null and release the player's resources.
  playerView.setPlayer(null);
  player.release();
  player = null;

  // Release the adsLoader state so that it can be initiated again.
  adsLoaderState = adsLoader.release();
}
MyActivity.java

טיפול באירועי שחקנים

כדי לטפל באירועים של השחקן, יוצרים קודים להתקשרות חזרה לאירועים של מחזור החיים של הפעילות כדי לנהל את הפעלת הסטרימינג.

ב-Android API ברמה 24 ומעלה, משתמשים בשיטות הבאות:

לרמות API של Android מגרסה מוקדמת יותר מ-24, משתמשים בשיטות הבאות:

השיטות onStart() ו-onResume() ממופות ל-playerView.onResume(), ואילו השיטות onStop() ו-onPause() ממופות ל-playerView.onPause().

בשלב הזה נעשה שימוש גם באירוע onSaveInstanceState() כדי לשמור את adsLoaderState.

@Override
public void onStart() {
  super.onStart();
  if (Util.SDK_INT > 23) {
    initializePlayer();
    if (playerView != null) {
      playerView.onResume();
    }
  }
}

@Override
public void onResume() {
  super.onResume();
  if (Util.SDK_INT <= 23 || player == null) {
    initializePlayer();
    if (playerView != null) {
      playerView.onResume();
    }
  }
}

@Override
public void onPause() {
  super.onPause();
  if (Util.SDK_INT <= 23) {
    if (playerView != null) {
      playerView.onPause();
    }
    releasePlayer();
  }
}

@Override
public void onStop() {
  super.onStop();
  if (Util.SDK_INT > 23) {
    if (playerView != null) {
      playerView.onPause();
    }
    releasePlayer();
  }
}

@Override
public void onSaveInstanceState(Bundle outState) {
  // Attempts to save the AdsLoader state to handle app backgrounding.
  if (adsLoaderState != null) {
    outState.putBundle(KEY_ADS_LOADER_STATE, adsLoaderState.toBundle());
  }
}
MyActivity.java

הגדרה של שידור VOD (אופציונלי)

אם באפליקציה שלכם צריך להפעיל תוכן VOD עם מודעות, אתם צריכים לפעול לפי השלבים הבאים:

מוסיפים CMS ID ו-Video ID לשידור VOD. לצורך בדיקה, משתמשים בפרמטרים הבאים של השידור:
- מזהה מערכת ניהול תוכן: "2548831"
- מזהה סרטון: "tears-of-steel"

יוצרים URI של VOD עם SSAI באמצעות ה-method‏ ImaServerSideAdInsertionUriBuilder():

/**
 * Builds an IMA SSAI VOD stream URI for the given CMS ID, video ID, and format.
 *
 * @param cmsId The CMS ID of the VOD stream.
 * @param videoId The video ID of the VOD stream.
 * @param format The format of the VOD stream request, either {@code CONTENT_TYPE_HLS} or {@code
 *     CONTENT_TYPE_DASH}.
 * @return The URI of the VOD stream.
 */
public Uri buildVodStreamUri(String cmsId, String videoId, int format) {
  Map<String, String> adTagParams = new HashMap<String, String>();
  // Update the adTagParams map with any parameters.
  // For more information, see https://support.google.com/admanager/answer/7320899

  return new ImaServerSideAdInsertionUriBuilder()
      .setContentSourceId(cmsId)
      .setVideoId(videoId)
      .setFormat(format)
      .setAdTagParameters(adTagParams)
      .build();
}
MyActivity.java

מגדירים את ה-URI החדש של סטרימינג ה-VOD כפריט המדיה של הנגן באמצעות השיטה MediaItem.fromUri().

אם הפעולה מצליחה, אפשר לבקש ולהפעיל זרם מדיה באמצעות התוסף ExoPlayer IMA. לדוגמה המלאה, אפשר לעיין בדוגמאות ל-DAI ב-Android ב-GitHub.