เริ่มต้นใช้งานส่วนขยาย IMA ของ Exoplayer

IMA SDK ช่วยให้ผสานรวมโฆษณามัลติมีเดียลงในเว็บไซต์และแอปได้อย่างง่ายดาย IMA SDK สามารถส่งคําขอโฆษณาจากเซิร์ฟเวอร์โฆษณา ที่เป็นไปตามข้อกําหนดของ VAST ใดก็ได้ และจัดการการเล่นโฆษณาในแอป เมื่อใช้ SDK ฝั่งไคลเอ็นต์ IMA คุณจะยังคงควบคุมการเล่นวิดีโอเนื้อหาได้ ขณะที่ SDK จะจัดการการเล่นโฆษณา โฆษณาจะเล่นในวิดีโอเพลเยอร์แยกต่างหากที่วางอยู่ด้านบนของวิดีโอเพลเยอร์ของเนื้อหาแอป

คู่มือนี้สาธิตวิธีผสานรวม IMA SDK เข้ากับโปรเจ็กต์ Android Studio ที่ว่างเปล่าโดยใช้ส่วนขยาย IMA ของ ExoPlayer หากต้องการดูหรือทําตามตัวอย่างการผสานรวมที่เสร็จสมบูรณ์ ให้ดาวน์โหลด BasicExample จาก GitHub

ภาพรวมฝั่งไคลเอ็นต์ของ IMA

การใช้ IMA ฝั่งไคลเอ็นต์ประกอบด้วยองค์ประกอบ SDK หลัก 4 อย่างดังที่แสดงในคู่มือนี้

  • AdDisplayContainer: ออบเจ็กต์คอนเทนเนอร์ที่ระบุตําแหน่งที่ IMA จะแสดงผลองค์ประกอบ UI ของโฆษณาและวัดการมองเห็นโฆษณา ซึ่งรวมถึงมุมมองแอ็กทีฟและการวัดผลแบบเปิด
  • AdsLoader: ออบเจ็กต์ที่ขอโฆษณาและจัดการเหตุการณ์จากการตอบกลับคำขอโฆษณา คุณควรสร้างอินสแตนซ์ของโปรแกรมโหลดโฆษณาเพียงรายการเดียว ซึ่งสามารถนำมาใช้ซ้ำได้ตลอดอายุการใช้งานของแอปพลิเคชัน
  • AdsRequest: ออบเจ็กต์ที่กําหนดคําขอโฆษณา คําขอโฆษณาจะระบุ URL สําหรับแท็กโฆษณา VAST รวมถึงพารามิเตอร์เพิ่มเติม เช่น มิติข้อมูลโฆษณา
  • AdsManager: ออบเจ็กต์ที่มีคำตอบสำหรับคำขอโฆษณา ควบคุมการเล่นโฆษณา และคอยฟังเหตุการณ์โฆษณาที่ SDK เรียกให้แสดง

ข้อกำหนดเบื้องต้น

ก่อนเริ่ม คุณต้องมี Android Studio 3.0 ขึ้นไป

1. สร้างโปรเจ็กต์ Android Studio ใหม่

หากต้องการสร้างโปรเจ็กต์ Android Studio ให้ทำตามขั้นตอนต่อไปนี้

  1. เริ่ม Android Studio
  2. เลือกเริ่มโปรเจ็กต์ Android Studio ใหม่
  3. ในหน้าเลือกโปรเจ็กต์ ให้เลือกเทมเพลตกิจกรรมว่าง
  4. คลิกถัดไป
  5. ในหน้ากําหนดค่าโปรเจ็กต์ ให้ตั้งชื่อโปรเจ็กต์และเลือก Java เป็นภาษา
  6. คลิกเสร็จสิ้น

2. เพิ่มส่วนขยาย IMA ของ ExoPlayer ลงในโปรเจ็กต์

ก่อนอื่น ให้เพิ่มการนําเข้าสําหรับส่วนขยายลงในส่วน Dependency ของไฟล์ build.gradle ระดับแอปพลิเคชัน เนื่องจากขนาดของส่วนขยาย IMA ของ ExoPlayer ให้ติดตั้งและเปิดใช้ MultiDex ที่นี่ ซึ่งจำเป็นสำหรับแอปที่ตั้งค่า minSdkVersion เป็น 20 หรือต่ำกว่า นอกจากนี้ ให้เพิ่ม compileOptions ใหม่เพื่อระบุข้อมูลความเข้ากันได้ของเวอร์ชัน Java

app/build.gradle
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 ของโฆษณา

สร้างมุมมองเพื่อใช้เป็น PlayerView ของ ExoPlayer โดยสร้างออบเจ็กต์ StyledPlayerView ที่มีรหัสที่เหมาะสม และเปลี่ยน androidx.constraintlayout.widget.ConstraintLayout เป็น LinearLayout ด้วย

app/src/main/res/layout/activity_main.xml
<?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

app/src/main/res/values/strings.xml
<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

app/src/main/java/com/example/project name/MainActivity.java

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 แท็กโฆษณา

app/src/main/java/com/example/project name/MainActivity.java
...

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 และกำหนดให้กับเพลเยอร์

app/src/main/java/com/example/project name/MainActivity.java
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
app/src/main/java/com/example/project name/MainActivity.java
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