IMA SDK ช่วยให้การผสานรวมโฆษณามัลติมีเดียลงในเว็บไซต์และแอปเป็นเรื่องง่าย IMA SDK สามารถขอโฆษณาจากเซิร์ฟเวอร์โฆษณาที่ สอดคล้องกับ VAST และจัดการการเล่นโฆษณาในแอปของคุณ เมื่อใช้ IMA DAI SDK แอปจะส่งคำขอสตรีมสำหรับโฆษณาและวิดีโอเนื้อหาไม่ว่าจะเป็น VOD หรือเนื้อหาสด จากนั้น SDK จะแสดงสตรีมวิดีโอแบบรวมเพื่อให้คุณไม่ต้องจัดการการสลับระหว่างโฆษณาและวิดีโอเนื้อหาภายในแอป
เลือกโซลูชัน DAI ที่สนใจ
DAI สำหรับบริการเต็มรูปแบบ
คู่มือนี้แสดงวิธีผสานรวม IMA SDK เข้ากับแอปโปรแกรมเล่นวิดีโออย่างง่าย หากคุณต้องการดูหรือทำตามการผสานรวมตัวอย่างที่สมบูรณ์ ให้ดาวน์โหลด BasicExample จาก GitHub
ภาพรวม IMA DAI
การใช้งาน IMA DAI ประกอบด้วยองค์ประกอบ SDK หลัก 4 ส่วนดังที่แสดงในคู่มือนี้
StreamDisplayContainer: คอนเทนเนอร์ออบเจ็กต์ที่อยู่ด้านบนองค์ประกอบการเล่นวิดีโอและจัดเก็บองค์ประกอบ UI ของโฆษณาAdsLoader: ออบเจ็กต์ที่ขอสตรีมและจัดการเหตุการณ์ที่ทริกเกอร์โดยออบเจ็กต์การตอบกลับคำขอสตรีม คุณควรสร้างอินสแตนซ์ตัวโหลดโฆษณาเพียงรายการเดียวเท่านั้น ซึ่งสามารถนำมาใช้ซ้ำได้ตลอดอายุของแอปพลิเคชันStreamRequest: ออบเจ็กต์ที่กำหนดคำขอสตรีม คำขอสตรีมอาจเป็นได้ทั้งวิดีโอออนดีมานด์หรือสตรีมแบบสด คำขอจะระบุ Content ID รวมทั้งคีย์ API หรือโทเค็นการตรวจสอบสิทธิ์ และพารามิเตอร์อื่นๆStreamManager: ออบเจ็กต์ที่จัดการสตรีมการแทรกโฆษณาแบบไดนามิกและการโต้ตอบกับแบ็กเอนด์ DAI ตัวจัดการสตรีมจะจัดการกับคำสั่ง ping ของการติดตาม รวมถึงส่งต่อเหตุการณ์ของสตรีมและเหตุการณ์โฆษณาไปยังผู้เผยแพร่โฆษณาด้วย
ข้อกำหนดเบื้องต้น
- Android Studio
- ตัวอย่างแอปโปรแกรมเล่นวิดีโอสำหรับการผสานรวม SDK
ดาวน์โหลดและเรียกใช้แอปโปรแกรมเล่นวิดีโอตัวอย่าง
แอปตัวอย่างมีโปรแกรมเล่นวิดีโอที่ใช้งานได้ซึ่งเล่นวิดีโอ HLS ใช้รายงานนี้เป็นจุดเริ่มต้นในการผสานรวมความสามารถ DAI ของ IMA Android SDK
ดาวน์โหลดตัวอย่างแอปโปรแกรมเล่นวิดีโอและดึงข้อมูล
เริ่ม Android Studio แล้วเลือกเปิดโปรเจ็กต์ Android Studio ที่มีอยู่ หรือหาก Android Studio กำลังทำงานอยู่ ให้เลือกไฟล์ > ใหม่ > นำเข้าโปรเจ็กต์ จากนั้นเลือก
SampleVideoPlayer/build.gradleเรียกใช้การซิงค์ Gradle โดยเลือกเครื่องมือ > Android > ซิงค์โปรเจ็กต์ด้วยไฟล์ Gradle
ตรวจสอบว่าแอปโปรแกรมเล่นคอมไพล์และทำงานบนอุปกรณ์ Android หรืออุปกรณ์เสมือนของ Android โดยใช้เรียกใช้ > เรียกใช้ "แอป" เป็นเรื่องปกติที่สตรีมวิดีโอ จะใช้เวลาโหลดสักครู่ก่อนที่จะเล่น
ตรวจสอบตัวอย่างวิดีโอเพลเยอร์
โปรแกรมเล่นวิดีโอตัวอย่างยังไม่มีโค้ดการผสานรวม IMA SDK แอปตัวอย่างประกอบด้วย 2 ส่วนหลัก ได้แก่
samplevideoplayer/SampleVideoPlayer.java: โปรแกรมเล่น HLS แบบ ExoPlayer ที่ใช้เป็นพื้นฐานสำหรับการผสานรวม IMA DAIvideoplayerapp/MyActivity.java: กิจกรรมนี้สร้างโปรแกรมเล่นวิดีโอ และส่งผ่านContextและSimpleExoPlayerView
เพิ่ม IMA Android SDK ลงในแอปโปรแกรมเล่น
คุณต้องรวมการอ้างอิงไปยัง IMA SDK ด้วย ใน Android Studio ให้เพิ่มข้อมูลต่อไปนี้ลงในไฟล์ build.gradle ระดับแอปพลิเคชันซึ่งอยู่ที่ app/build.gradle
repositories {
google()
mavenCentral()
}
dependencies {
implementation 'androidx.appcompat:appcompat:1.6.1'
implementation 'androidx.media3:media3-exoplayer:1.3.1'
implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.33.0'
}
ผสานรวม IMA SDK
สร้างคลาสใหม่ชื่อ
SampleAdsWrapperในแพ็กเกจvideoplayerapp(ในapp/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) เพื่อรวมSampleVideoPlayerที่มีอยู่และเพิ่มตรรกะที่ใช้ IMA DAI โดยคุณต้องสร้างAdsLoaderก่อน ซึ่งจะใช้ในการขอโฆษณาจากเซิร์ฟเวอร์โฆษณาvideoplayerapp/SampleAdsWrapper.java
package com.google.ads.interactivemedia.v3.samples.videoplayerapp; import android.annotation.TargetApi; import android.content.Context; import android.os.Build; import android.view.ViewGroup; import android.webkit.WebView; 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.AdsManagerLoadedEvent; import com.google.ads.interactivemedia.v3.api.CuePoint; import com.google.ads.interactivemedia.v3.api.ImaSdkFactory; import com.google.ads.interactivemedia.v3.api.ImaSdkSettings; import com.google.ads.interactivemedia.v3.api.StreamDisplayContainer; import com.google.ads.interactivemedia.v3.api.StreamManager; import com.google.ads.interactivemedia.v3.api.StreamRequest; import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate; import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer; import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer; import java.util.ArrayList; import java.util.HashMap; import java.util.List; public class SampleAdsWrapper implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener { // Livestream asset key. private static final String TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA"; // VOD content source and video IDs. private static final String TEST_CONTENT_SOURCE_ID = "2548831"; private static final String TEST_VIDEO_ID = "tears-of-steel"; private static final String PLAYER_TYPE = "DAISamplePlayer"; /** * Log interface, so you can output the log commands to the UI or similar. */ public interface Logger { void log(String logMessage); } private ImaSdkFactory sdkFactory; private AdsLoader adsLoader; private StreamDisplayContainer displayContainer; private StreamManager streamManager; private List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks; private SampleVideoPlayer videoPlayer; private Context context; private ViewGroup adUiContainer; private String fallbackUrl; private Logger logger; public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer, ViewGroup adUiContainer) { this.videoPlayer = videoPlayer; this.context = context; this.adUiContainer = adUiContainer; sdkFactory = ImaSdkFactory.getInstance(); playerCallbacks = new ArrayList<>(); createAdsLoader(); displayContainer = sdkFactory.createStreamDisplayContainer( this.adUiContainer, videoStreamPlayer ); } private void createAdsLoader() { ImaSdkSettings settings = new ImaSdkSettings(); adsLoader = sdkFactory.createAdsLoader(context); } public void requestAndPlayAds() { adsLoader.addAdErrorListener(this); adsLoader.addAdsLoadedListener(this); adsLoader.requestStream(buildStreamRequest()); } }เพิ่มเมธอด
buildStreamRequest()ลงในAdsLoaderเพื่อให้ขอสตรีมที่มีโฆษณาได้ โดยอาจเป็นสตรีมแบบสดที่มีโฆษณา (ตั้งค่าโดยค่าเริ่มต้น) หรือสตรีมวิดีโอออนดีมานด์(VOD) ที่เล่นเนื้อหาที่บันทึกไว้ล่วงหน้าพร้อมโฆษณา หากต้องการเปิดใช้สตรีม VOD ให้แสดงความคิดเห็นในคำขอสตรีมแบบสดและยกเลิกการแสดงความคิดเห็นในคำขอสตรีม VODโปรแกรมเล่นต้องส่งเหตุการณ์ ID3 สำหรับสตรีมแบบสดไปยัง IMA SDK เพื่อทำงานกับ DAI ในโค้ดตัวอย่างต่อไปนี้ ซึ่งจะดำเนินการโดยเมธอด
callback.onUserTextReceived()videoplayerapp/SampleAdsWrapper.java
private StreamRequest buildStreamRequest() { VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer(); videoPlayer.setSampleVideoPlayerCallback( new SampleVideoPlayer.SampleVideoPlayerCallback() { @Override public void onUserTextReceived(String userText) { for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) { callback.onUserTextReceived(userText); } } @Override public void onSeek(int windowIndex, long positionMs) { // See if you would seek past an ad, and if so, jump back to it. long newSeekPositionMs = positionMs; if (streamManager != null) { CuePoint prevCuePoint = streamManager.getPreviousCuePointForStreamTime(positionMs / 1000); if (prevCuePoint != null && !prevCuePoint.isPlayed()) { newSeekPositionMs = (long) (prevCuePoint.getStartTime() * 1000); } } videoPlayer.seekTo(windowIndex, newSeekPositionMs); } @Override public void onContentComplete() { for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) { callback.onContentComplete(); } } @Override public void onPause() { for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) { callback.onPause(); } } @Override public void onResume() { for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) { callback.onResume(); } } @Override public void onVolumeChanged(int percentage) { for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) { callback.onVolumeChanged(percentage); } } }); // Livestream request. StreamRequest request = sdkFactory.createLiveStreamRequest( TEST_ASSET_KEY, null, displayContainer); // VOD request. Comment the createLiveStreamRequest() line above and uncomment this // createVodStreamRequest() below to switch from a livestream to a VOD stream. // StreamRequest request = sdkFactory.createVodStreamRequest(TEST_CONTENT_SOURCE_ID, // TEST_VIDEO_ID, null, displayContainer); return request; }นอกจากนี้ คุณต้องมี
VideoStreamPlayerจึงจะเล่นสตรีมได้ ดังนั้นให้เพิ่มเมธอดcreateVideoStreamPlayer()ซึ่งจะสร้างคลาสที่ไม่ระบุตัวตนซึ่งใช้VideoStreamPlayervideoplayerapp/SampleAdsWrapper.java
private VideoStreamPlayer createVideoStreamPlayer() { VideoStreamPlayer player = new VideoStreamPlayer() { @Override public void loadUrl(String url, List<HashMap<String, String>> subtitles) { videoPlayer.setStreamUrl(url); videoPlayer.play(); } @Override public void addCallback( VideoStreamPlayerCallback videoStreamPlayerCallback) { playerCallbacks.add(videoStreamPlayerCallback); } @Override public void removeCallback( VideoStreamPlayerCallback videoStreamPlayerCallback) { playerCallbacks.remove(videoStreamPlayerCallback); } @Override public void onAdBreakStarted() { // Disable player controls. videoPlayer.enableControls(false); log("Ad Break Started\n"); } @Override public void onAdBreakEnded() { // Re-enable player controls. videoPlayer.enableControls(true); log("Ad Break Ended\n"); } @Override public VideoProgressUpdate getContentProgress() { return new VideoProgressUpdate(videoPlayer.getCurrentPosition(), videoPlayer.getDuration()); } }; return player; }นำ Listener ที่จำเป็นไปใช้และเพิ่มการรองรับสำหรับการจัดการข้อผิดพลาด
โปรดสังเกตการใช้งาน
AdErrorListenerเนื่องจากเป็นการเรียก URL สำรองหากโฆษณาเล่นไม่ได้ เนื่องจากเนื้อหาและโฆษณาอยู่ในสตรีมเดียว คุณต้องพร้อมเรียกใช้สตรีมสำรองหากสตรีม DAI พบข้อผิดพลาดvideoplayerapp/SampleAdsWrapper.java
/** AdErrorListener implementation **/ @Override public void onAdError(AdErrorEvent event) { // play fallback URL. videoPlayer.setStreamUrl(fallbackUrl); videoPlayer.enableControls(true); videoPlayer.play(); } /** AdEventListener implementation **/ @Override public void onAdEvent(AdEvent event) { switch (event.getType()) { case AD_PROGRESS: // Do nothing or else log are filled by these messages. break; default: log(String.format("Event: %s\n", event.getType())); break; } } /** AdsLoadedListener implementation **/ @Override public void onAdsManagerLoaded(AdsManagerLoadedEvent event) { streamManager = event.getStreamManager(); streamManager.addAdErrorListener(this); streamManager.addAdEventListener(this); streamManager.init(); } /** Sets fallback URL in case ads stream fails. **/ void setFallbackUrl(String url) { fallbackUrl = url; }เพิ่มในโค้ดสำหรับการบันทึก
videoplayerapp/SampleAdsWrapper.java
/** Sets logger for displaying events to screen. Optional. **/ void setLogger(Logger logger) { this.logger = logger; } private void log(String message) { if (logger != null) { logger.log(message); } }แก้ไข
MyActivityในvideoplayerappเพื่อสร้างอินสแตนซ์และเรียกใช้SampleAdsWrappervideoplayerapp/MyActivity.java
import android.view.ViewGroup; import android.widget.ScrollView; ... public class MyActivity extends AppCompatActivity { ... @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_my); View rootView = findViewById(R.id.videoLayout); videoPlayer = new SampleVideoPlayer(rootView.getContext(), (SimpleExoPlayerView) rootView.findViewById(R.id.playerView)); videoPlayer.enableControls(false); final SampleAdsWrapper sampleAdsWrapper = new SampleAdsWrapper(this, videoPlayer, (ViewGroup) rootView.findViewById(R.id.adUiContainer)); sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL); final ScrollView scrollView = (ScrollView) findViewById(R.id.logScroll); final TextView textView = (TextView) findViewById(R.id.logText); sampleAdsWrapper.setLogger(new SampleAdsWrapper.Logger() { @Override public void log(String logMessage) { Log.i(APP_LOG_TAG, logMessage); if (textView != null) { textView.append(logMessage); } if (scrollView != null) { scrollView.post(new Runnable() { @Override public void run() { scrollView.fullScroll(View.FOCUS_DOWN); } }); } } }); playButton = (ImageButton) rootView.findViewById(R.id.playButton); // Set up play button listener to play video then hide play button. playButton.setOnClickListener(new View.OnClickListener() { @Override public void onClick(View view) { sampleAdsWrapper.requestAndPlayAds(); playButton.setVisibility(View.GONE); } }); } ... }แก้ไขไฟล์เลย์เอาต์ของกิจกรรม
activity_my.xmlเพื่อเพิ่มองค์ประกอบ UI สำหรับการบันทึกres/layout/activity_my.xml
... <TextView android:id="@+id/playerDescription" android:text="@string/video_description" android:textAlignment="center" android:gravity="center_horizontal" android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="0.1" android:textSize="@dimen/font_size" /> <!-- UI element for viewing SDK event log --> <ScrollView android:id="@+id/logScroll" android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="0.5" android:padding="5dp" android:background="#DDDDDD"> <TextView android:id="@+id/logText" android:layout_width="match_parent" android:layout_height="wrap_content"> </TextView> </ScrollView> ...
ยินดีด้วย คุณกำลังขอและแสดงโฆษณาวิดีโอในแอป Android เพื่อปรับแต่งการใช้งาน โปรดดูที่ บุ๊กมาร์ก, Snapback และเอกสาร API
การแก้ปัญหา
หากพบปัญหาขณะเล่นโฆษณาวิดีโอ ให้ลองดาวน์โหลด BasicExample ที่สมบูรณ์ หากใช้งานได้อย่างถูกต้องใน BasicExample แสดงว่าอาจมีปัญหาเกี่ยวกับโค้ดการผสานรวม IMA ของแอป
หากยังพบปัญหาอยู่ ให้ไปที่ฟอรัม IMA SDK