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

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

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

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

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

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

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

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

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

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

• Android Studio
• AndroidX Media3 ExoPlayer גרסה 1.0.0 ואילך לתמיכה בהטמעת מודעות דינמיות.

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

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

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

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

  הערה: IMA DAI SDK תואם ל-Kotlin. עם זאת, הדוגמה שמופיעה במדריך הזה משתמשת ב-Java.

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

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

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

מגדירים את האפליקציה ל-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 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 SDK -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    ...

</manifest>

הוספה של הצהרות Intent

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

הערה: גרסאות עתידיות של IMA 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.

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

לדוגמה:

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' אם יש צורך בספירת השיטות של האפליקציה וב-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.CREATOR.fromBundle(
                adsLoaderStateBundle);
      }
    }
  }

}

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

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

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

הערה: בקטע הזה נעשה שימוש בשיטות עם שמות שמפנים למושגים של הכנסת מודעות בצד השרת (SSAI).

• הטמעת מודעות דינמיות ב-Google Ad Manager היא מופע של SSAI.
• ההטמעה של תוסף IMA של ExoPlayer במדריך הזה מיועדת לפעול באופן ספציפי עם הטמעת מודעות דינמיות ב-Ad Manager. תוספי IMA של ExoPlayer תומכים גם במופעי SSAI אחרים, כמו Google Cloud Platform, שלא מופיעים במדריך הזה.

לדוגמה:

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().

נקודה חשובה: הדוגמה הזו מתייחסת גם ל-Android SDK בגרסה 24 ואילך וגם בגרסאות עד 24. צריך להשתמש ב-onStart()/onStop() ל-Android SDK בגרסה 24 ואילך וב-onResume()/onPause() לגרסאות שקודמות ל-24.

בשלב הזה נעשה שימוש גם באירוע 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 = "2528370";
  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);
  }

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