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

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

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

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

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

תמיכה בסטרימינג בתוסף ExoPlayer-IMA
	סטרימינג בשידור חי	שידורי VOD
HLS
DASH

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

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

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

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

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

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

• מפעילים את Android Studio.
• בוחרים באפשרות התחלת פרויקט חדש של Android Studio.
• בדף Choose your project, בוחרים את התבנית No activity (ללא פעילות).
• לוחצים על הבא.

• בדף Configure your project, נותנים שם לפרויקט ובוחרים ב-Java לשפה.

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

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

מוסיפים ייבוא של התוסף לקובץ build.gradle ברמת האפליקציה, בקטע dependencies.

מגדירים את האפליקציה כך ומפעילים את האפשרות multidex. העדכון הזה נדרש בגלל גודל התוסף, והוא נדרש באפליקציות שבהן minSdkVersion מוגדר ל-Android 4.4W (רמת API 20) ומטה.

לדוגמה:

app/build.gradle

android {

  ...

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp"
      minSdkVersion 19
      targetSdkVersion 34
      multiDexEnabled true
      versionCode 1
      versionName "1.0"
  }

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.media3:media3-ui:1.1.1'
    implementation 'androidx.media3:media3-exoplayer:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-hls:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-dash:1.1.1'

    // Adding the ExoPlayer IMA extension for ads will also include the IMA
    // SDK as a dependency.
    implementation 'androidx.media3:media3-exoplayer-ima:1.1.1'
}

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

app/src/main/AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.project name">

    <!-- Required permissions for the IMA DAI SDK -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    ...

</manifest>

הוספת הצהרות לגבי Intent

אם האפליקציה שלכם מטרגטת את Android 11 (רמת API 30) ואילך, לגרסאות הנוכחיות והעדכניות של IMA DAI SDK נדרשת הצהרת כוונות מפורשת כדי לפתוח קישורים לאינטרנט. כדי לאפשר קליקים על מודעות (משתמשים שלוחצים על הלחצן למידע נוסף), צריך להוסיף את קטע הקוד הבא לקובץ המניפסט של האפליקציה.

  <?xml version="1.0" encoding="utf-8"?>
  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.example.project name">

      ...

    </application>

    <queries>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="https" />
      </intent>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="http" />
      </intent>
    </queries>
  </manifest>

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

יוצרים את האובייקט PlayerView שישמש את ExoPlayer.

משנים את הערך של androidx.constraintlayout.widget.ConstraintLayout ל-LinearLayout, המומלץ לתוסף IMA של ExoPlayer.

לדוגמה:

app/src/main/res/layout/activity_my.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:background="@android:color/black"
    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:layout_width="match_parent"
        android:layout_height="match_parent" />

</LinearLayout>

הוספת הפרמטרים של השידור

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

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

ייבוא תוסף IMA של ExoPlayer

צריך להוסיף את הצהרות הייבוא של תוסף ExoPlayer.

מוסיפים את המשתנים הפרטיים הבאים אל MyActivity.java:

• PlayerView
• ExoPlayer
• ImaServerSideAdInsertionMediaSource.AdsLoader
• ImaServerSideAdInsertionMediaSource.AdsLoader.State

מוסיפים את מַפתח הנכס של השידור Big Buck Bunny (Live) כדי לבדוק את הסטרימינג הזה. שידורי סטרימינג נוספים זמינים לבדיקה בדף השידור לדוגמה של IMA.

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

לדוגמה:

app/src/main/java/com/example/project name/MyActivity.java

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

import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import androidx.annotation.Nullable;
import androidx.annotation.OptIn;
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.exoplayer.util.EventLogger;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

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 PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

}

יצירת מכונה של adsLoader

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

בנוסף, מפעילים את האפשרות multidex אם הפעולה נדרשת בהתאם למספר ה-methods באפליקציה ול-minSdkVersion (כפי שמוסבר בשלב 2).

לדוגמה:

app/src/main/java/com/example/project name/MyActivity.java

...

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 PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

  @Override
  protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_my);
    MultiDex.install(this);

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

}

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

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

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

לדוגמה:

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  ...

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

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

    return adsLoaderBuilder.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 an ExoPlayer and set it as the player for content and ads.
    player = new ExoPlayer.Builder(this).setMediaSourceFactory(mediaSourceFactory).build();
    playerView.setPlayer(player);
    adsLoader.setPlayer(player);

    // Build an IMA SSAI media item to prepare the player with.
    Uri ssaiLiveUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setAssetKey(SAMPLE_ASSET_KEY)
            .setFormat(CONTENT_TYPE_HLS) // Use CONTENT_TYPE_DASH for dash streams.
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiLiveUri);

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

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

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

• מגדירים את קובצי העזר של הנגן כ-null ומשחררים את המשאבים שלו.
• צריך לשחרר את המצב של adsLoader.

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  ...

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

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

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

כדי לתמוך ב-Android SDK בגרסה 24 ואילך:

• onStart()
• onStop()

כדי לתמוך בגרסאות Android SDK שקודמות ל-24: - onResume() - onPause()

onStart() ו-onResume() ממפים לplayerView.onResume(), ו-onStop() ו-onPause() ממפים לplayerView.onPause().

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

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  ...

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

  ...

}

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

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

1. צריך להוסיף CMS ID ו-Video ID לשידור בדיקה ב-VOD.
2. יוצרים URI של SSAI VOD באמצעות ImaServerSideAdInsertionUriBuilder().
3. משתמשים ב-URI החדש הזה כפריט המדיה של הנגן.

app/src/main/java/com/example/project name/MyActivity.java

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 SAMPLE_CMS_ID = "2548831";
  private static final String SAMPLE_VIDEO_ID = "tears-of-steel";

  ...

  private void initializePlayer() {

     ...

    Uri ssaiVodUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setContentSourceId(SAMPLE_CMS_ID)
            .setVideoId(SAMPLE_VIDEO_ID)
            .setFormat(CONTENT_TYPE_HLS)
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiVodUri);

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

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