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.
לוחצים על סיום.
הוספת התוסף ExoPlayer IMA לפרויקט
מוסיפים את היבוא של התוסף לקובץ build.gradle ברמת האפליקציה בקטע dependencies
.
צריך להגדיר את האפליקציה ולהפעיל אותה
multidex הפעולה הזו נדרשת עקב
לגודל התוסף, צריך להגדיר אותו באפליקציות שבהן המאפיין minSdkVersion
מוגדר
ל-Android 4.4W (רמת API)
20) או פחות.
לדוגמה:
app/build.gradle
android { ... defaultConfig { applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp" minSdkVersion 21 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>
הוספת הצהרות כוונות
אם האפליקציה שלכם מטרגטת את 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 דף בשביל מקור נתונים לדוגמה כדי לבדוק את הפרויקט. אפשר גם לעיין בקטע בנושא DAI ב-Ad Manager כדי לקבל מידע על הגדרת מקורות הנתונים שלכם.
השלב הזה מדגים הגדרת שידור חי, אבל ExoPlayer IMA התוסף תומך גם בשידורי DAI VOD. בשלב הזה מוסבר אילו שינויים צריך לבצע באפליקציה כדי לטפל בשידורי VOD.
ייבוא תוסף IMA של ExoPlayer
צריך להוסיף את הצהרות הייבוא של תוסף ExoPlayer.
מוסיפים את המשתנים הפרטיים הבאים אל MyActivity.java
:
PlayerView
ExoPlayer
ImaServerSideAdInsertionMediaSource.AdsLoader
ImaServerSideAdInsertionMediaSource.AdsLoader.State
כדי לבדוק באמצעות זה, צריך להוסיף את מַפתח הנכס של שידור ה-HLS של 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 ואילך:
כדי לתמוך בגרסאות 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 עם מודעות, יהיה עליך לעשות זאת הבאים:
- מוסיפים
CMS ID
ו-Video ID
לשידור VOD לבדיקה. - יוצרים URI של SSAI VOD באמצעות
ImaServerSideAdInsertionUriBuilder()
. - משתמשים ב-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 כדי לקבל את הקוד המלא.