ערכות ה-SDK של IMA מאפשרות לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות שלכם. ערכות ה-SDK של IMA יכולות לבקש מודעות מכל שרת מודעות שתואם ל-VAST ולנהל את ההפעלה של המודעות באפליקציות. באמצעות ערכות SDK של IMA בצד הלקוח, אתם שומרים על השליטה בהפעלת סרטוני התוכן, בעוד ש-SDK מטפל בהפעלת המודעות. המודעות מופעלות בנגן וידאו נפרד שממוקם מעל נגן הווידאו של התוכן באפליקציה.
במדריך הזה נסביר איך לשלב את IMA SDK בפרויקט ריק ב-Android Studio באמצעות התוסף ExoPlayer IMA. אם אתם רוצים לראות או לפעול לפי דוגמה לשילוב שהושלם, תוכלו להוריד את BasicExample מ-GitHub.
סקירה כללית על IMA בצד הלקוח
הטמעת IMA בצד הלקוח כוללת ארבעה רכיבים עיקריים של SDK, שמתוארים במדריך הזה:
AdDisplayContainer
: אובייקט מאגר שמציין איפה IMA מעבדת את רכיבי ממשק המשתמש של המודעות וממדידה את הניראות, כולל Active View ו-Open Measurement.AdsLoader
: אובייקט שמבקש מודעות ומטפל באירועים מתשובות לבקשות להצגת מודעות. צריך ליצור רק אובייקט אחד של Ads Loader, שאפשר להשתמש בו שוב במהלך חיי האפליקציה.AdsRequest
: אובייקט שמגדיר בקשה להצגת מודעות. בבקשות להצגת מודעות מצוינות כתובת ה-URL של תג המודעה בפורמט VAST, וגם פרמטרים נוספים, כמו המאפיינים של המודעה.AdsManager
: אובייקט שמכיל את התגובה לבקשת המודעות, שולט בהפעלת המודעות ומקשיב לאירועי מודעות שמופעל על ידי ה-SDK.
דרישות מוקדמות
לפני שמתחילים, צריך להתקין את Android Studio בגרסה 3.0 ואילך.
1. יצירת פרויקט חדש ב-Android Studio
כדי ליצור פרויקט ב-Android Studio:
- פותחים את Android Studio.
- בוחרים באפשרות Start a new Android Studio project (התחלת פרויקט חדש ב-Android Studio).
- בדף Choose your project, בוחרים בתבנית Empty Activity.
- לוחצים על הבא.
- בדף Configure your project, נותנים שם לפרויקט ובוחרים את Java כשפה.
- לוחצים על סיום.
2. הוספת התוסף ExoPlayer IMA לפרויקט
קודם כול, בקובץ build.gradle ברמת האפליקציה, מוסיפים את ייבוא התוסף לקטע של יחסי התלות. בגלל הגודל של התוסף ExoPlayer IMA, צריך להטמיע ולהפעיל את multidex כאן. הדבר נדרש לאפליקציות שבהן הערך של minSdkVersion
מוגדר כ-20 או פחות.
בנוסף, מוסיפים compileOptions
חדש כדי לציין את פרטי התאימות לגרסה של Java.
android { namespace 'com.google.ads.interactivemedia.v3.samples.exoplayerexample' compileSdkVersion 34 compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } } defaultConfig { applicationId "com.google.ads.interactivemedia.v3.samples.exoplayerexample" 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.3.1' implementation 'androidx.media3:media3-exoplayer:1.3.1' implementation 'androidx.media3:media3-exoplayer-ima:1.3.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>
הוספת הצהרות כוונות
אם האפליקציה שלכם מטרגטת ל-Android 11 (רמת API 30) ואילך, הגרסאות הנוכחיות והעדכניות של 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>
3. יצירת הקונטיינר של ממשק המשתמש של המודעה
יוצרים את התצוגה שתשמש כ-PlayerView של ExoPlayer על ידי יצירת אובייקט StyledPlayerView
עם מזהה מתאים. צריך גם לשנות את הערך של androidx.constraintlayout.widget.ConstraintLayout
ל-LinearLayout
.
<?xml version="1.0" encoding="utf-8"?> <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:app="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools" android:layout_width="match_parent" android:layout_height="match_parent" tools:context=".MainActivity"> <androidx.media3.ui.PlayerView android:id="@+id/player_view" android:layout_width="match_parent" android:layout_height="wrap_content" /> </LinearLayout>
4. מוסיפים את כתובת ה-URL של התוכן ואת כתובת ה-URL של תג המודעות לבקשת המודעות
מוסיפים רשומות ל-strings.xml
כדי לאחסן את כתובת ה-URL של התוכן ואת כתובת ה-URL של תג המודעה מסוג VAST.
<resources> <string name="app_name">Your_Project_Name</string> <string name="content_url"><![CDATA[https://storage.googleapis.com/gvabox/media/samples/stock.mp4]]></string> <string name="ad_tag_url"><![CDATA[https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=]]></string> </resources>
5. ייבוא התוסף של ExoPlayer IMA
מוסיפים את הצהרות הייבוא של תוסף ExoPlayer. לאחר מכן, מעדכנים את הכיתה MainActivity
כך שתרחיב את Activity
על ידי הוספת משתנים פרטיים עבור PlayerView
, SimpleExoPlayer
ו-ImaAdsLoader
.
import android.app.Activity; import android.net.Uri; import android.os.Bundle; 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.ImaAdsLoader; import androidx.media3.exoplayer.source.DefaultMediaSourceFactory; import androidx.media3.exoplayer.source.MediaSource; import androidx.media3.ui.PlayerView; import androidx.multidex.MultiDex; ... public class MainActivity extends Activity { private PlayerView playerView; private ExoPlayer player; private ImaAdsLoader adsLoader; }
6. יצירת מכונה של adsLoader
מחליפים את השיטה onCreate
ומוסיפים את הקצאות המשתנים הנדרשות כדי ליצור אובייקט adsLoader
חדש עם כתובת ה-URL של תג המודעה.
... public class MainActivity extends Activity { private PlayerView playerView; private ExoPlayer player; private ImaAdsLoader adsLoader; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); MultiDex.install(this); playerView = findViewById(R.id.player_view); // Create an AdsLoader. adsLoader = new ImaAdsLoader.Builder(/* context= */ this) .setAdEventListener(buildAdEventListener()) .build(); } public AdEvent.AdEventListener buildAdEventListener() { AdEvent.AdEventListener imaAdEventListener = event -> { AdEvent.AdEventType eventType = event.getType(); // Log IMA events for debugging. // The ExoPlayer IMA extension already handles IMA events and does not need anything // additional here to function. }; return imaAdEventListener; } }
7. איך מפעילים ומבטלים את הנגן
מוסיפים שיטות לאינטליקציה ולשחרור הנגן. יוצרים את SimpleExoPlayer
בשיטת initialize. לאחר מכן יוצרים את AdsMediaSource
ומגדירים אותו לנגן.
public class MainActivity extends Activity { ... private void releasePlayer() { adsLoader.setPlayer(null); playerView.setPlayer(null); player.release(); player = null; } private void initializePlayer() { // Set up the factory for media sources, passing the ads loader and ad view providers. DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this); MediaSource.Factory mediaSourceFactory = new DefaultMediaSourceFactory(dataSourceFactory) .setLocalAdInsertionComponents(unusedAdTagUri -> adsLoader, playerView); // 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); // Create the MediaItem to play, specifying the content URI and ad tag URI. Uri contentUri = Uri.parse(getString(R.string.content_url)); Uri adTagUri = Uri.parse(getString(R.string.ad_tag_url)); MediaItem mediaItem = new MediaItem.Builder() .setUri(contentUri) .setAdsConfiguration(new MediaItem.AdsConfiguration.Builder(adTagUri).build()) .build(); // Prepare the content and ad to be played with the SimpleExoPlayer. player.setMediaItem(mediaItem); player.prepare(); // Set PlayWhenReady. If true, content and ads will autoplay. player.setPlayWhenReady(false); } }
8. טיפול באירועי שחקנים
לבסוף, יוצרים קודים להתקשרות חזרה לאירועים במחזור החיים של השחקן:
onStart
onResume
onStop
onPause
onDestroy
public class MainActivity extends Activity { private PlayerView playerView; private SimpleExoPlayer player; private ImaAdsLoader adsLoader; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_my); playerView = findViewById(R.id.player_view); // Create an AdsLoader. adsLoader = new ImaAdsLoader.Builder(/* context= */ this) .setAdEventListener(buildAdEventListener()) .build(); } @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 protected void onDestroy() { super.onDestroy(); adsLoader.release(); } ... }
זהו! עכשיו אתם שולחים בקשות למודעות ומציגים אותן באמצעות IMA SDK. למידע נוסף על תכונות נוספות של ה-SDK, אפשר לעיין במדריכים האחרים או בדוגמאות ב-GitHub.