IMA SDK מאפשר לכם לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות שלכם. IMA SDK יכול לשלוח בקשה להצגת מודעות מכל שרת מודעות שתואם ל-VAST ולנהל את ההפעלה של המודעות באפליקציות שלך. ערכות SDK בצד הלקוח של IMA מאפשרות לך לשלוט בהפעלה של תוכן וידאו, בעוד מערכת ה-SDK מטפלת בהפעלת המודעות. המודעות מופעלות בנגן וידאו נפרד שממוקם מעל נגן הווידאו של תוכן האפליקציה.
מדריך זה מדגים איך לשלב את IMA SDK בפרויקט ריק ב-Android Studio באמצעות Android VideoView להצגת תוכן ומודעות. כדי לראות את השילוב לדוגמה המלא, הורידו את BasicExample מ-GitHub.
סקירה כללית של IMA בצד הלקוח
ההטמעה של IMA בצד הלקוח כוללת ארבעה רכיבי SDK עיקריים, שמפורטים במדריך הזה:
AdDisplayContainer
: אובייקט מאגר תגים שבו מודעות מעובדות.AdsLoader
: אובייקט שמבקש מודעות ומטפל באירועים מתגובות לבקשות למודעות. יש להפעיל רק טוען מודעות אחד, שניתן לעשות בו שימוש חוזר במהלך חיי האפליקציה.AdsRequest
: אובייקט שמגדיר בקשה להצגת מודעות. בקשות להצגת מודעות מציינות את כתובת ה-URL של תג המודעה VAST, וגם פרמטרים נוספים, כמו מאפייני המודעה.AdsManager
: אובייקט שמכיל את התגובה לבקשה להצגת מודעה, שולט בהפעלת המודעות ומאזין לאירועי מודעות שהופעלו על ידי ה-SDK.
דרישות מוקדמות
1. יצירת פרויקט חדש ב-Android Studio
כדי ליצור פרויקט Android Studio, מבצעים את השלבים הבאים:
- מפעילים את Android Studio.
- בוחרים באפשרות התחלת פרויקט חדש ב-Android Studio.
- בדף Choose your project, בוחרים את התבנית Empty Activity.
- לוחצים על הבא.
- בדף Configure your project, נותנים שם לפרויקט ובוחרים ב-Java לשפה.
- לוחצים על סיום.
2. הוספת IMA SDK לפרויקט
קודם כול, בקובץ build.gradle ברמת האפליקציה, מוסיפים ייבוא של IMA SDK לקטע של יחסי התלות. בגלל הגודל של IMA SDK, כדאי להטמיע ולהפעיל את Multidex כאן. הפעולה הזו נדרשת באפליקציות שבהן הערך של minSdkVersion
מוגדר ל-20 ומטה. בנוסף, צריך להוסיף compileOptions
חדש כדי לציין את פרטי התאימות של גרסת Java.
android { namespace 'com.google.ads.interactivemedia.v3.samples.videoplayerapp' compileSdkVersion 34 compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } defaultConfig { applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp" minSdkVersion 21 targetSdkVersion 34 multiDexEnabled true versionCode 1 versionName "1.0" } ... } dependencies { implementation 'androidx.appcompat:appcompat:1.6.1' implementation 'androidx.browser:browser:1.6.0' implementation 'androidx.media:media:1.6.0' implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.34.0' ... }
3. צריך להוסיף את ההרשאות הנדרשות ל-IMA SDK
הוסף את הרשאות המשתמש הנדרשות על ידי 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>
4. עדכון הפריסה של האפליקציה
צריך לעדכן את פריסת האפליקציה כך שתכלול VideoView
כדי להפעיל גם תוכן וגם
מודעות.
<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"> <RelativeLayout android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="0.4" android:orientation="vertical" android:id="@+id/videoPlayerContainer" > <VideoView android:id="@+id/videoView" android:layout_width="match_parent" android:layout_height="match_parent" /> <ImageButton android:id="@+id/playButton" android:contentDescription="@string/play_description" android:layout_width="match_parent" android:layout_height="match_parent" android:src="@drawable/ic_action_play_over_video" android:background="@null" /> </RelativeLayout> <FrameLayout android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="0.6" android:id="@+id/videoDescription" > <TextView android:id="@+id/playerDescription" android:text="@string/app_name" android:textAlignment="center" android:gravity="center_horizontal" android:layout_width="match_parent" android:layout_height="match_parent" android:textSize="@dimen/font_size" /> </FrameLayout> </LinearLayout>
5. ייבוא IMA לפעילות העיקרית
מוסיפים את הצהרות הייבוא של IMA SDK. לאחר מכן, מעדכנים את
המחלקה MyActivity
כך שתרחיב את משך הזמן של AppCompatActivity
. המחלקה AppCompatActivity
מאפשרת תמיכה בתכונות פלטפורמה חדשות יותר במכשירי Android ישנים יותר. לאחר מכן, מוסיפים קבוצה של משתנים פרטיים שיהיו בשימוש באפליקציה.
import android.content.Context; import android.media.AudioManager; import android.os.Bundle; import android.support.v7.app.AppCompatActivity; import android.util.Log; import android.view.View; import android.view.ViewGroup; import android.widget.MediaController; import android.widget.VideoView; import com.google.ads.interactivemedia.v3.api.AdDisplayContainer; import com.google.ads.interactivemedia.v3.api.AdErrorEvent; import com.google.ads.interactivemedia.v3.api.AdEvent; import com.google.ads.interactivemedia.v3.api.AdsLoader; import com.google.ads.interactivemedia.v3.api.AdsManager; import com.google.ads.interactivemedia.v3.api.AdsManagerLoadedEvent; import com.google.ads.interactivemedia.v3.api.AdsRenderingSettings; import com.google.ads.interactivemedia.v3.api.AdsRequest; import com.google.ads.interactivemedia.v3.api.ImaSdkFactory; import com.google.ads.interactivemedia.v3.api.ImaSdkSettings; import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate; import java.util.Arrays; ... public class MyActivity extends AppCompatActivity { private static final String LOGTAG = "IMABasicSample"; private static final String SAMPLE_VIDEO_URL = "https://storage.googleapis.com/gvabox/media/samples/stock.mp4"; /** * IMA sample tag for a single skippable inline video ad. See more IMA sample tags at * https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags */ private static final String SAMPLE_VAST_TAG_URL = "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/" + "single_preroll_skippable&sz=640x480&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast" + "&unviewed_position_start=1&env=vp&impl=s&correlator="; // Factory class for creating SDK objects. private ImaSdkFactory sdkFactory; // The AdsLoader instance exposes the requestAds method. private AdsLoader adsLoader; // AdsManager exposes methods to control ad playback and listen to ad events. private AdsManager adsManager; // The saved content position, used to resumed content following an ad break. private int savedPosition = 0; // This sample uses a VideoView for content and ad playback. For production // apps, Android's Exoplayer offers a more fully featured player compared to // the VideoView. private VideoView videoPlayer; private MediaController mediaController; private View playButton; private VideoAdPlayerAdapter videoAdPlayerAdapter; }
6. יצירת המחלקה VideoAdPlayerAdapter
יצירת מחלקה VideoAdPlayerAdapter
באמצעות VideoView
,
והתאמה שלה לממשק
VideoAdPlayer
של IMA. הכיתה הזו תטפל בתוכן ובהפעלת מודעות, ותכיל את
השיטות שבהן נגן וידאו צריך להשתמש כדי להשתמש ב-IMA SDK.
import android.media.AudioManager; import android.media.MediaPlayer; import android.net.Uri; import android.util.Log; import android.widget.VideoView; import com.google.ads.interactivemedia.v3.api.AdPodInfo; import com.google.ads.interactivemedia.v3.api.player.AdMediaInfo; import com.google.ads.interactivemedia.v3.api.player.VideoAdPlayer; import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate; import java.util.ArrayList; import java.util.List; import java.util.Timer; import java.util.TimerTask; /** Example implementation of IMA's VideoAdPlayer interface. */ public class VideoAdPlayerAdapter implements VideoAdPlayer { private static final String LOGTAG = "IMABasicSample"; private static final long POLLING_TIME_MS = 250; private static final long INITIAL_DELAY_MS = 250; private final VideoView videoPlayer; private final AudioManager audioManager; private final List<VideoAdPlayerCallback> videoAdPlayerCallbacks = new ArrayList<>(); private Timer timer; private int adDuration; // The saved ad position, used to resumed ad playback following an ad click-through. private int savedAdPosition; private AdMediaInfo loadedAdMediaInfo; public VideoAdPlayerAdapter(VideoView videoPlayer, AudioManager audioManager) { this.videoPlayer = videoPlayer; this.videoPlayer.setOnCompletionListener( (MediaPlayer mediaPlayer) -> notifyImaOnContentCompleted()); this.audioManager = audioManager; } }
7. שינוי השיטות של VideoAdPlayer
אפשר לשנות את השיטות הבאות של VideoAdPlayer
:
השיטה playAd()
מגדירה את כתובת ה-URL של התוכן או המודעה ומגדירה מאזין להתחיל את ההפעלה
לאחר טעינת המדיה.
/** Example implementation of IMA's VideoAdPlayer interface. */ public class VideoAdPlayerAdapter implements VideoAdPlayer { ... @Override public void addCallback(VideoAdPlayerCallback videoAdPlayerCallback) { videoAdPlayerCallbacks.add(videoAdPlayerCallback); } @Override public void loadAd(AdMediaInfo adMediaInfo, AdPodInfo adPodInfo) { // This simple ad loading logic works because preloading is disabled. To support // preloading ads your app must maintain state for the currently playing ad // while handling upcoming ad downloading and buffering at the same time. // See the IMA Android preloading guide for more info: // https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/preload loadedAdMediaInfo = adMediaInfo; } @Override public void pauseAd(AdMediaInfo adMediaInfo) { Log.i(LOGTAG, "pauseAd"); savedAdPosition = videoPlayer.getCurrentPosition(); stopAdTracking(); } @Override public void playAd(AdMediaInfo adMediaInfo) { videoPlayer.setVideoURI(Uri.parse(adMediaInfo.getUrl())); videoPlayer.setOnPreparedListener( mediaPlayer -> { adDuration = mediaPlayer.getDuration(); if (savedAdPosition > 0) { mediaPlayer.seekTo(savedAdPosition); } mediaPlayer.start(); startAdTracking(); }); videoPlayer.setOnErrorListener( (mediaPlayer, errorType, extra) -> notifyImaSdkAboutAdError(errorType)); videoPlayer.setOnCompletionListener( mediaPlayer -> { savedAdPosition = 0; notifyImaSdkAboutAdEnded(); }); } @Override public void release() { // any clean up that needs to be done. } @Override public void removeCallback(VideoAdPlayerCallback videoAdPlayerCallback) { videoAdPlayerCallbacks.remove(videoAdPlayerCallback); } @Override public void stopAd(AdMediaInfo adMediaInfo) { Log.i(LOGTAG, "stopAd"); stopAdTracking(); } /** Returns current volume as a percent of max volume. */ @Override public int getVolume() { return audioManager.getStreamVolume(AudioManager.STREAM_MUSIC) / audioManager.getStreamMaxVolume(AudioManager.STREAM_MUSIC); }
8. הגדרת מעקב אחר מודעות
כדי שאירועי מודעות יירשמו,
יש להפעיל את VideoAdPlayerCallback.onAdProgress
בתור תוכן והתקדמות של מודעות. כדי לתמוך באפשרות הזו, צריך להגדיר טיימר כדי להתקשר אל onAdProgress()
במרווחי זמן קבועים.
/** Example implementation of IMA's VideoAdPlayer interface. */ public class VideoAdPlayerAdapter implements VideoAdPlayer { ... private void startAdTracking() { Log.i(LOGTAG, "startAdTracking"); if (timer != null) { return; } timer = new Timer(); TimerTask updateTimerTask = new TimerTask() { @Override public void run() { VideoProgressUpdate progressUpdate = getAdProgress(); notifyImaSdkAboutAdProgress(progressUpdate); } }; timer.schedule(updateTimerTask, POLLING_TIME_MS, INITIAL_DELAY_MS); } private void notifyImaSdkAboutAdEnded() { Log.i(LOGTAG, "notifyImaSdkAboutAdEnded"); savedAdPosition = 0; for (VideoAdPlayer.VideoAdPlayerCallback callback : videoAdPlayerCallbacks) { callback.onEnded(loadedAdMediaInfo); } } private void notifyImaSdkAboutAdProgress(VideoProgressUpdate adProgress) { for (VideoAdPlayer.VideoAdPlayerCallback callback : videoAdPlayerCallbacks) { callback.onAdProgress(loadedAdMediaInfo, adProgress); } } /** * @param errorType Media player's error type as defined at * https://cs.android.com/android/platform/superproject/+/master:frameworks/base/media/java/android/media/MediaPlayer.java;l=4335 * @return True to stop the current ad playback. */ private boolean notifyImaSdkAboutAdError(int errorType) { Log.i(LOGTAG, "notifyImaSdkAboutAdError"); switch (errorType) { case MediaPlayer.MEDIA_ERROR_UNSUPPORTED: Log.e(LOGTAG, "notifyImaSdkAboutAdError: MEDIA_ERROR_UNSUPPORTED"); break; case MediaPlayer.MEDIA_ERROR_TIMED_OUT: Log.e(LOGTAG, "notifyImaSdkAboutAdError: MEDIA_ERROR_TIMED_OUT"); break; default: break; } for (VideoAdPlayer.VideoAdPlayerCallback callback : videoAdPlayerCallbacks) { callback.onError(loadedAdMediaInfo); } return true; } public void notifyImaOnContentCompleted() { Log.i(LOGTAG, "notifyImaOnContentCompleted"); for (VideoAdPlayer.VideoAdPlayerCallback callback : videoAdPlayerCallbacks) { callback.onContentComplete(); } } private void stopAdTracking() { Log.i(LOGTAG, "stopAdTracking"); if (timer != null) { timer.cancel(); timer = null; } } @Override public VideoProgressUpdate getAdProgress() { long adPosition = videoPlayer.getCurrentPosition(); return new VideoProgressUpdate(adPosition, adDuration); } }
9. הפעלת IMA בשיטה onCreate
מחליפים את השיטה onCreate
ומוסיפים את הקצאות המשתנים הנדרשות כדי להפעיל
IMA. בשלב הזה יוצרים את ההגדרות הבאות:
ImaSdkSettings
AdsLoader
השלב הזה יוצר גם VideoAdPlayerAdapter
, כיתה שתיווצר מאוחר יותר
במדריך הזה.
לסיום, מגדירים את לחצן ההפעלה כדי לבקש מודעות. לאחר מכן, יוסתרו כשלוחצים עליו.
app/src/main/java/com/example/project name/MyActivity.java... public class MyActivity extends AppCompatActivity { ... private VideoView videoPlayer; private MediaController mediaController; private View playButton; private VideoAdPlayerAdapter videoAdPlayerAdapter; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_my); // Create the UI for controlling the video view. mediaController = new MediaController(this); videoPlayer = findViewById(R.id.videoView); mediaController.setAnchorView(videoPlayer); videoPlayer.setMediaController(mediaController); // Create an ad display container that uses a ViewGroup to listen to taps. ViewGroup videoPlayerContainer = findViewById(R.id.videoPlayerContainer); AudioManager audioManager = (AudioManager) getSystemService(Context.AUDIO_SERVICE); videoAdPlayerAdapter = new VideoAdPlayerAdapter(videoPlayer, audioManager); sdkFactory = ImaSdkFactory.getInstance(); AdDisplayContainer adDisplayContainer = ImaSdkFactory.createAdDisplayContainer(videoPlayerContainer, videoAdPlayerAdapter); // Create an AdsLoader. ImaSdkSettings settings = sdkFactory.createImaSdkSettings(); adsLoader = sdkFactory.createAdsLoader(this, settings, adDisplayContainer); // When the play button is clicked, request ads and hide the button. playButton = findViewById(R.id.playButton); playButton.setOnClickListener( view -> { videoPlayer.setVideoPath(SAMPLE_VIDEO_URL); requestAds(SAMPLE_VAST_TAG_URL); view.setVisibility(View.GONE); }); } }
10. הוספת פונקציות מסוג AdsLoader
מוסיפים מאזינים ל-addAdErrorListener
ול-addAdsLoadedListener
. ב-AdsLoadedListener
, יוצרים את
AdsManager
ומגדירים את פונקציית ההאזנה AdsManager
לשגיאות.
@Override protected void onCreate(Bundle savedInstanceState) { ... // Create an AdsLoader. ImaSdkSettings settings = sdkFactory.createImaSdkSettings(); adsLoader = sdkFactory.createAdsLoader(this, settings, adDisplayContainer); // Add listeners for when ads are loaded and for errors. adsLoader.addAdErrorListener( new AdErrorEvent.AdErrorListener() { /** An event raised when there is an error loading or playing ads. */ @Override public void onAdError(AdErrorEvent adErrorEvent) { Log.i(LOGTAG, "Ad Error: " + adErrorEvent.getError().getMessage()); resumeContent(); } }); adsLoader.addAdsLoadedListener( new AdsLoader.AdsLoadedListener() { @Override public void onAdsManagerLoaded(AdsManagerLoadedEvent adsManagerLoadedEvent) { // Ads were successfully loaded, so get the AdsManager instance. AdsManager has // events for ad playback and errors. adsManager = adsManagerLoadedEvent.getAdsManager(); // Attach event and error event listeners. adsManager.addAdErrorListener( new AdErrorEvent.AdErrorListener() { /** An event raised when there is an error loading or playing ads. */ @Override public void onAdError(AdErrorEvent adErrorEvent) { Log.e(LOGTAG, "Ad Error: " + adErrorEvent.getError().getMessage()); String universalAdIds = Arrays.toString(adsManager.getCurrentAd().getUniversalAdIds()); Log.i( LOGTAG, "Discarding the current ad break with universal " + "ad Ids: " + universalAdIds); adsManager.discardAdBreak(); } }); } });
11. טיפול באירועי IMA של מודעות
האזנה לאירועי מודעות IMA בעזרת
AdsManager.addAdEventListener
. ניתן להגדיר פעולות לאירועי IMA הבאים על סמך הצהרת מתג:
קטע הקוד כולל הערות עם מידע נוסף על אופן השימוש באירועים. אחרי שמגדירים את האירועים, אפשר להתקשר אל AdsManager.init()
.
adsLoader.addAdsLoadedListener( new AdsLoader.AdsLoadedListener() { @Override public void onAdsManagerLoaded(AdsManagerLoadedEvent adsManagerLoadedEvent) { ... adsManager.addAdEventListener( new AdEvent.AdEventListener() { /** Responds to AdEvents. */ @Override public void onAdEvent(AdEvent adEvent) { if (adEvent.getType() != AdEvent.AdEventType.AD_PROGRESS) { Log.i(LOGTAG, "Event: " + adEvent.getType()); } // These are the suggested event types to handle. For full list of // all ad event types, see AdEvent.AdEventType documentation. switch (adEvent.getType()) { case LOADED: // AdEventType.LOADED is fired when ads are ready to play. // This sample app uses the sample tag // single_preroll_skippable_ad_tag_url that requires calling // AdsManager.start() to start ad playback. // If you use a different ad tag URL that returns a VMAP or // an ad rules playlist, the adsManager.init() function will // trigger ad playback automatically and the IMA SDK will // ignore the adsManager.start(). // It is safe to always call adsManager.start() in the // LOADED event. adsManager.start(); break; case CONTENT_PAUSE_REQUESTED: // AdEventType.CONTENT_PAUSE_REQUESTED is fired when you // should pause your content and start playing an ad. pauseContentForAds(); break; case CONTENT_RESUME_REQUESTED: // AdEventType.CONTENT_RESUME_REQUESTED is fired when the ad // you should play your content. resumeContent(); break; case ALL_ADS_COMPLETED: // Calling adsManager.destroy() triggers the function // VideoAdPlayer.release(). adsManager.destroy(); adsManager = null; break; case CLICKED: // When the user clicks on the Learn More button, the IMA SDK fires // this event, pauses the ad, and opens the ad's click-through URL. // When the user returns to the app, the IMA SDK calls the // VideoAdPlayer.playAd() function automatically. break; default: break; } } }); AdsRenderingSettings adsRenderingSettings = ImaSdkFactory.getInstance().createAdsRenderingSettings(); adsManager.init(adsRenderingSettings); }
12. טיפול במעבר בין מודעות לתוכן
בקטע הזה יוצרים את השיטות pauseContentForAds
ו-resumeContent
שצוינו בשלבים הקודמים. השיטות האלה ישתמשו מחדש בנגן כדי להפעיל
גם תוכן וגם מודעות. עליך לעקוב אחר מיקום התוכן כדי
להמשיך את ההפעלה לאחר ההפסקה למודעה.
/** Main activity. */ public class MyActivity extends AppCompatActivity { ... private void pauseContentForAds() { Log.i(LOGTAG, "pauseContentForAds"); savedPosition = videoPlayer.getCurrentPosition(); videoPlayer.stopPlayback(); // Hide the buttons and seek bar controlling the video view. videoPlayer.setMediaController(null); } private void resumeContent() { Log.i(LOGTAG, "resumeContent"); // Show the buttons and seek bar controlling the video view. videoPlayer.setVideoPath(SAMPLE_VIDEO_URL); videoPlayer.setMediaController(mediaController); videoPlayer.setOnPreparedListener( mediaPlayer -> { if (savedPosition > 0) { mediaPlayer.seekTo(savedPosition); } mediaPlayer.start(); }); videoPlayer.setOnCompletionListener( mediaPlayer -> videoAdPlayerAdapter.notifyImaOnContentCompleted()); } }
13. בקשה להצגת מודעות
עכשיו מוסיפים את השיטה requestAds
כדי ליצור AdsRequest
ומשתמשים בה כדי לבצע קריאה אל AdsLoader.requestAds()
.
/** Main activity. */ public class MyActivity extends AppCompatActivity { ... private void requestAds(String adTagUrl) { // Create the ads request. AdsRequest request = sdkFactory.createAdsRequest(); request.setAdTagUrl(adTagUrl); request.setContentProgressProvider( () -> { if (videoPlayer.getDuration() <= 0) { return VideoProgressUpdate.VIDEO_TIME_NOT_READY; } return new VideoProgressUpdate( videoPlayer.getCurrentPosition(), videoPlayer.getDuration()); }); // Request the ad. After the ad is loaded, onAdsManagerLoaded() will be called. adsLoader.requestAds(request); } }
זהו! הבקשה שלך להצגת מודעות מתבצעת עכשיו באמצעות IMA SDK. כדי לקבל מידע על תכונות נוספות של SDK, אפשר לעיין במדריכים האחרים או בדוגמאות ב-GitHub.