IMA SDK ช่วยให้การผสานรวมโฆษณามัลติมีเดียลงในเว็บไซต์และแอปเป็นเรื่องง่าย IMA SDK สามารถขอโฆษณาจากเซิร์ฟเวอร์โฆษณาที่ สอดคล้องกับ VAST และจัดการการเล่นโฆษณาในแอปของคุณ เมื่อใช้ SDK ฝั่งไคลเอ็นต์ของ IMA คุณจะเป็นผู้ควบคุมการเล่นวิดีโอเนื้อหา ส่วน SDK จะจัดการการเล่นโฆษณา โฆษณาจะเล่นในโปรแกรมเล่นวิดีโอแยกต่างหากซึ่งอยู่ที่ด้านบนของโปรแกรมเล่นวิดีโอเนื้อหาของแอป
คู่มือนี้สาธิตวิธีผสานรวม IMA SDK เข้ากับโปรเจ็กต์ Android Studio ที่ว่างเปล่าโดยใช้ส่วนขยาย IMA ของ ExoPlayer หากต้องการดูหรือติดตามพร้อมกับการผสานรวมตัวอย่างที่สมบูรณ์ ให้ดาวน์โหลด BasicExample จาก GitHub
ภาพรวมฝั่งไคลเอ็นต์ของ IMA
การใช้ฝั่งไคลเอ็นต์ของ IMA ประกอบด้วยองค์ประกอบ SDK หลัก 4 รายการ ดังที่แสดงในคู่มือนี้
AdDisplayContainer
: คอนเทนเนอร์ออบเจ็กต์ที่แสดงโฆษณาAdsLoader
: ออบเจ็กต์ที่ขอโฆษณาและจัดการเหตุการณ์จากการตอบกลับคำขอโฆษณา คุณควรยืนยันตัวโหลดโฆษณาเพียง 1 ตัวเท่านั้น ซึ่งสามารถนำมาใช้ซ้ำได้ตลอดอายุของแอปพลิเคชันAdsRequest
: ออบเจ็กต์ที่กำหนดคำขอโฆษณา คำขอโฆษณาจะระบุ URL สำหรับแท็กโฆษณา VAST รวมถึงพารามิเตอร์เพิ่มเติม เช่น มิติข้อมูลโฆษณาAdsManager
: ออบเจ็กต์ที่มีการตอบกลับคำขอโฆษณา ควบคุมการเล่นโฆษณา และการรอฟังเหตุการณ์โฆษณาที่ SDK เริ่มการทำงาน
ข้อกำหนดเบื้องต้น
ก่อนเริ่มใช้งาน คุณต้องใช้ Android Studio 3.0 ขึ้นไป
1. สร้างโปรเจ็กต์ Android Studio ใหม่
หากต้องการสร้างโปรเจ็กต์ Android Studio ให้ทำตามขั้นตอนต่อไปนี้
- เริ่มใช้ Android Studio
- เลือกเริ่มโปรเจ็กต์ Android Studio ใหม่
- ในหน้าเลือกโปรเจ็กต์ ให้เลือกเทมเพลตกิจกรรมที่ว่างเปล่า
- คลิกถัดไป
- ในหน้ากำหนดค่าโปรเจ็กต์ ให้ตั้งชื่อโปรเจ็กต์แล้วเลือกภาษา Java
- คลิกเสร็จ
2. เพิ่มส่วนขยาย IMA ของ ExoPlayer ลงในโปรเจ็กต์
ก่อนอื่น ในไฟล์ build.gradle ระดับแอปพลิเคชัน ให้เพิ่มการนำเข้าสำหรับส่วนขยายลงในส่วน
ทรัพยากร Dependency เนื่องจากส่วนขยาย 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>
เพิ่มการประกาศ Intent
หากแอปกำหนดเป้าหมายเป็น Android 11 (API ระดับ 30) ขึ้นไป เวอร์ชันปัจจุบันและเวอร์ชันล่าสุดของ IMA SDK กำหนดให้ต้องประกาศความตั้งใจเพื่อเปิดเว็บลิงก์อย่างชัดเจน เพิ่มข้อมูลโค้ดต่อไปนี้ลงในไฟล์ Manifest ของแอปเพื่อเปิดใช้การคลิกผ่านโฆษณา (ผู้ใช้คลิกปุ่มดูข้อมูลเพิ่มเติม)<?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. สร้างคอนเทนเนอร์ UI ของโฆษณา
สร้างมุมมองเพื่อใช้เป็น ExoPlayer PlayerView โดยการสร้างออบเจ็กต์ 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. นำเข้าส่วนขยาย IMA ของ ExoPlayer
เพิ่มคำสั่งการนำเข้าสำหรับส่วนขยาย 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
จากนั้นสร้าง 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