IMA SDK 可讓您輕鬆將多媒體廣告整合至您的網站和應用程式。IMA SDK 可以 向任何 與 VAST 相容的廣告伺服器,並管理您應用程式中的廣告播放方式。使用 IMA 用戶端 SDK 您能掌控內容影片播放,而 SDK 會處理廣告播放。廣告在 獨立影片播放器位於應用程式內容影片播放器上方。
本指南說明如何使用 ExoPlayer IMA 擴充功能。 如要查看或按照已完成的整合範例操作,請下載 GitHub 的 BasicExample。
IMA 用戶端總覽
導入 IMA 用戶端需要四個主要的 SDK 元件,如本例所示 指南:
AdDisplayContainer
: 廣告顯示位置的容器物件。AdsLoader
: 這個物件會請求廣告,以及處理廣告請求回應中的事件。除了 將一個廣告載入器執行個體化,以便在應用程式生命週期中重複使用。AdsRequest
: 定義廣告請求的物件。廣告請求會指定 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. 建立廣告 UI 容器
建立 StyledPlayerView
,建立要做為 ExoPlayer PlayerView 的檢視畫面
並提交適當 ID 的物件一併變更
將 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. 為廣告請求新增內容網址和廣告代碼網址
將項目新增至 strings.xml
,以儲存內容網址和 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
物件 (包含廣告代碼網址)
... 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 上的範例。