หน้านี้ได้รับการแปลโดย Cloud Translation API

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

ExoPlayer เป็น โปรแกรมเล่นสื่อระดับแอปพลิเคชันสำหรับ Android คู่มือนี้จะแสดงวิธีใช้ส่วนขยาย IMA ของ ExoPlayer ซึ่งรวมถึง IMA Android DAI SDK ในการขอและเล่นสตรีมสื่อซึ่งมีทั้งโฆษณาและเนื้อหา

ประโยชน์ของส่วนขยายมีดังนี้

ลดความซับซ้อนของโค้ดที่จำเป็นในการผสานรวม IMA กับฟีเจอร์ต่างๆ
ลดเวลาในการพัฒนาที่ต้องใช้ในการอัปเดตเป็น IMA เวอร์ชันใหม่

ส่วนขยาย ExoPlayer IMA รองรับโปรโตคอลสตรีมมิง HLS และ DASH นี่คือสรุป

การรองรับสตรีมส่วนขยาย ExoPlayer-IMA
	ไลฟ์สด	สตรีม VOD
HLS
หน้าแดชบอร์ด

ExoPlayer-IMA เวอร์ชัน 1.1.0 ขึ้นไปรองรับสตรีมแบบสด DASH ได้

คู่มือนี้อิงจากคู่มือ ExoPlayer ซึ่งแสดง วิธีสร้างแอปเต็มรูปแบบและผสานรวมส่วนขยาย โปรดดู ExoPlayerExample จาก GitHub สำหรับตัวอย่าง พร้อมตัวอย่างแอปที่สมบูรณ์

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

Android Studio
AndroidX Media3 ExoPlayer เวอร์ชัน 1.0.0 ขึ้นไปสำหรับการรองรับ DAI

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

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

เริ่มใช้ Android Studio
เลือกเริ่มโปรเจ็กต์ Android Studio ใหม่
ในหน้าเลือกโปรเจ็กต์ ให้เลือกเทมเพลตไม่มีกิจกรรม
คลิกถัดไป
ในหน้ากำหนดค่าโปรเจ็กต์ ให้ตั้งชื่อโปรเจ็กต์แล้วเลือกภาษาของ Java

หมายเหตุ: IMA DAI SDK ใช้งานได้กับ Kotlin แต่ตัวอย่างที่อธิบายในคู่มือนี้ใช้ Java
คลิกเสร็จสิ้น

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

เพิ่มการนำเข้าสำหรับส่วนขยายลงในไฟล์ build.gradle ระดับแอปพลิเคชันในส่วน dependencies

กำหนดค่าแอปและเปิดใช้ multidex ซึ่งจำเป็นเนื่องจากขนาดของส่วนขยาย และจำเป็นสำหรับแอปที่ตั้งค่า minSdkVersion เป็น Android 4.4W (API ระดับ 20) หรือต่ำกว่า

ตัวอย่าง

app/build.gradle

android {

  ...

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp"
      minSdkVersion 19
      targetSdkVersion 34
      multiDexEnabled true
      versionCode 1
      versionName "1.0"
  }

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.media3:media3-ui:1.1.1'
    implementation 'androidx.media3:media3-exoplayer:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-hls:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-dash:1.1.1'

    // Adding the ExoPlayer IMA extension for ads will also include the IMA
    // SDK as a dependency.
    implementation 'androidx.media3:media3-exoplayer-ima:1.1.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>

ตั้งค่า UI ของ ExoPlayer

สร้างออบเจ็กต์ PlayerView เพื่อให้ ExoPlayer ใช้

เปลี่ยน androidx.constraintlayout.widget.ConstraintLayout เป็น LinearLayout ซึ่งแนะนำสำหรับส่วนขยาย IMA ของ ExoPlayer

ตัวอย่าง

app/src/main/res/layout/activity_my.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:background="@android:color/black"
    android:id="@+id/container"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    tools:context=".MyActivity"
    tools:ignore="MergeRootFrame">

    <androidx.media3.ui.PlayerView
        android:id="@+id/player_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</LinearLayout>

เพิ่มพารามิเตอร์สตรีม

ดูหน้าสตรีมตัวอย่าง IMA สำหรับตัวอย่างเนื้อหาสตรีมเพื่อทดสอบโปรเจ็กต์ของคุณ นอกจากนี้ โปรดดูส่วน Ad Manager เกี่ยวกับ DAI เพื่อดูข้อมูลเกี่ยวกับการตั้งค่าสตรีมของคุณเอง

ขั้นตอนนี้จะสาธิตการตั้งค่าสตรีมแบบสด แต่ส่วนขยาย IMA ของ ExoPlayer รองรับสตรีม DAI VOD ด้วย ดูขั้นตอนสำหรับสตรีมวิดีโอออนดีมานด์ (VOD) เพื่อดูการเปลี่ยนแปลงที่แอปต้องจัดการสตรีม VOD

นำเข้าส่วนขยาย IMA ของ ExoPlayer

เพิ่มคำสั่งการนำเข้าสำหรับส่วนขยาย ExoPlayer

เพิ่มตัวแปรส่วนตัวต่อไปนี้ใน MyActivity.java

เพิ่มคีย์เนื้อหาของสตรีม HLS ของ Big Buck Bunny (การถ่ายทอดสด) เพื่อทดสอบกับสตรีมนี้ มีสตรีมอื่นๆ ให้ทดสอบในหน้าสตรีมตัวอย่างของ IMA

สร้างค่าคงที่ KEY_ADS_LOADER_STATE เพื่อบันทึกและเรียกสถานะ AdsLoader

ตัวอย่าง

app/src/main/java/com/example/`project name`/MyActivity.java


import static androidx.media3.common.C.CONTENT_TYPE_HLS;

import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import androidx.annotation.Nullable;
import androidx.annotation.OptIn;
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.ImaServerSideAdInsertionMediaSource;
import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionUriBuilder;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.util.EventLogger;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

public class MyActivity extends Activity {

  private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
  private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

}

สร้างอินสแตนซ์ `adsLoader`

เขียนทับเมธอด onCreate เพื่อค้นหา PlayerView และตรวจหา AdsLoader.State ที่บันทึกไว้ ซึ่งสามารถใช้เมื่อเริ่มต้นออบเจ็กต์ adsLoader ได้

รวมถึงเปิดใช้ Multidex หากจำเป็นสำหรับจำนวนเมธอดของแอปและ minSdkVersion (ตามที่อธิบายไว้ในขั้นตอนที่ 2)

ตัวอย่าง

app/src/main/java/com/example/`project name`/MyActivity.java

...

public class MyActivity extends Activity {

  private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
  private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

  @Override
  protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_my);
    MultiDex.install(this);

    playerView = findViewById(R.id.player_view);

    // Checks if there is a saved AdsLoader state to be used later when
    // initiating the AdsLoader.
    if (savedInstanceState != null) {
      Bundle adsLoaderStateBundle = savedInstanceState.getBundle(KEY_ADS_LOADER_STATE);
      if (adsLoaderStateBundle != null) {
        adsLoaderState =
            ImaServerSideAdInsertionMediaSource.AdsLoader.State.CREATOR.fromBundle(
                adsLoaderStateBundle);
      }
    }
  }

}

เพิ่มวิธีการเริ่มต้นโปรแกรมเล่น

เพิ่มวิธีการเพื่อเริ่มต้นโปรแกรมเล่นและดำเนินการดังต่อไปนี้

สร้างอินสแตนซ์ AdsLoader
สร้าง ExoPlayer
สร้าง MediaItem ด้วยคีย์เนื้อหาของสตรีมแบบสด
ตั้งค่า MediaItem ไปยังโปรแกรมเล่นของคุณ

หมายเหตุ: ส่วนนี้ใช้เมธอดที่มีชื่ออ้างอิงถึงแนวคิดการแทรกโฆษณาฝั่งเซิร์ฟเวอร์ (SSAI)

Google Ad Manager DAI เป็นอินสแตนซ์ของ SSAI
การใช้งานส่วนขยาย ExoPlayer IMA ของคู่มือนี้ออกแบบมาเพื่อทำงานกับ Ad Manager DAI โดยเฉพาะ ส่วนขยาย ExoPlayer IMA ยังรองรับอินสแตนซ์ SSAI อื่นๆ ด้วย เช่น Google Cloud Platform ซึ่งไม่ได้แสดงอยู่ในคู่มือนี้

ตัวอย่าง

app/src/main/java/com/example/`project name`/MyActivity.java

public class MyActivity extends Activity {

  ...

  
  // Create a server side ad insertion (SSAI) AdsLoader.
  private ImaServerSideAdInsertionMediaSource.AdsLoader createAdsLoader() {
    ImaServerSideAdInsertionMediaSource.AdsLoader.Builder adsLoaderBuilder =
        new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(this, playerView);

    // Attempt to set the AdsLoader state if available from a previous session.
    if (adsLoaderState != null) {
      adsLoaderBuilder.setAdsLoaderState(adsLoaderState);
    }

    return adsLoaderBuilder.build();
  }

  private void initializePlayer() {
    adsLoader = createAdsLoader();

    // Set up the factory for media sources, passing the ads loader.
    DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);
    DefaultMediaSourceFactory mediaSourceFactory = new DefaultMediaSourceFactory(dataSourceFactory);

    // MediaSource.Factory to create the ad sources for the current player.
    ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory =
        new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, mediaSourceFactory);

    // 'mediaSourceFactory' is an ExoPlayer component for the DefaultMediaSourceFactory.
    // 'adsMediaSourceFactory' is an ExoPlayer component for a MediaSource factory for IMA server
    // side inserted ad streams.
    mediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory);

    // 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);

    // Build an IMA SSAI media item to prepare the player with.
    Uri ssaiLiveUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setAssetKey(SAMPLE_ASSET_KEY)
            .setFormat(CONTENT_TYPE_HLS) // Use CONTENT_TYPE_DASH for dash streams.
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiLiveUri);

    // Prepare the content and ad to be played with the ExoPlayer.
    player.setMediaItem(ssaiMediaItem);
    player.prepare();

    // Set PlayWhenReady. If true, content and ads will autoplay.
    player.setPlayWhenReady(false);
  }
}

เพิ่มวิธีการปล่อยโปรแกรมเล่น

เพิ่มวิธีการปล่อยโปรแกรมเล่นในลำดับนี้

ตั้งค่าการอ้างอิงผู้เล่นเป็น Null และปล่อยทรัพยากรของผู้เล่น
ปล่อยสถานะของ adsLoader

app/src/main/java/com/example/`project name`/MyActivity.java

public class MyActivity extends Activity {

  ...

  private void releasePlayer() {
    // Set the player references to null and release the player's resources.
    playerView.setPlayer(null);
    player.release();
    player = null;

    // Release the adsLoader state so that it can be initiated again.
    adsLoaderState = adsLoader.release();
  }

จัดการเหตุการณ์ของผู้เล่น

สุดท้าย ให้สร้างโค้ดเรียกกลับสำหรับเหตุการณ์ในวงจรของกิจกรรมเพื่อจัดการการเล่นสตรีม

วิธีรองรับ Android SDK เวอร์ชัน 24 ขึ้นไป

เพื่อรองรับ Android SDK เวอร์ชันที่ต่ำกว่า 24 - onResume() - onPause()

onStart() และ onResume() แมปไปยัง playerView.onResume() และ onStop() และ onPause() แมปไปยัง playerView.onPause()

ขั้นตอนนี้ยังใช้เหตุการณ์ onSaveInstanceState() เพื่อพยายามบันทึก adsLoaderState ด้วย

app/src/main/java/com/example/`project name`/MyActivity.java

public class MyActivity extends Activity {

  ...

  @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
  public void onSaveInstanceState(Bundle outState) {
    // Attempts to save the AdsLoader state to handle app backgrounding.
    if (adsLoaderState != null) {
      outState.putBundle(KEY_ADS_LOADER_STATE, adsLoaderState.toBundle());
    }
  }

  ...

}

การตั้งค่าสตรีม VOD (ไม่บังคับ)

หากกำหนดให้แอปเล่นเนื้อหา VOD แบบมีโฆษณา คุณจะต้องทำดังต่อไปนี้

เพิ่ม CMS ID และ Video ID สำหรับสตรีมทดสอบ VOD
สร้าง URI ของ SSAI VOD โดยใช้ ImaServerSideAdInsertionUriBuilder()
ใช้ URI ใหม่นี้เป็นรายการสื่อของโปรแกรมเล่น

app/src/main/java/com/example/`project name`/MyActivity.java

public class MyActivity extends Activity {

  private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
  private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
  private static final String SAMPLE_CMS_ID = "2528370";
  private static final String SAMPLE_VIDEO_ID = "tears-of-steel";

  ...

  private void initializePlayer() {

     ...

    Uri ssaiVodUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setContentSourceId(SAMPLE_CMS_ID)
            .setVideoId(SAMPLE_VIDEO_ID)
            .setFormat(CONTENT_TYPE_HLS)
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiVodUri);

    // Prepare the content and ad to be played with the ExoPlayer.
    player.setMediaItem(ssaiMediaItem);
    player.prepare();

    // Set PlayWhenReady. If true, content and ads will autoplay.
    player.setPlayWhenReady(false);
  }

เท่านี้ก็เรียบร้อย คุณกำลังขอและเล่นสตรีมสื่อด้วยส่วนขยาย IMA ของ ExoPlayer ดูตัวอย่าง Android DAI ใน GitHub เพื่อดูโค้ดทั้งหมด

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

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

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

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

app/build.gradle

app/src/main/AndroidManifest.xml

เพิ่มการประกาศ Intent

ตั้งค่า UI ของ ExoPlayer

app/src/main/res/layout/activity_my.xml

เพิ่มพารามิเตอร์สตรีม

นำเข้าส่วนขยาย IMA ของ ExoPlayer

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

สร้างอินสแตนซ์ adsLoader

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

เพิ่มวิธีการเริ่มต้นโปรแกรมเล่น

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

เพิ่มวิธีการปล่อยโปรแกรมเล่น

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

จัดการเหตุการณ์ของผู้เล่น

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

การตั้งค่าสตรีม VOD (ไม่บังคับ)

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

app/src/main/java/com/example/`project name`/MyActivity.java

สร้างอินสแตนซ์ `adsLoader`

app/src/main/java/com/example/`project name`/MyActivity.java

app/src/main/java/com/example/`project name`/MyActivity.java

app/src/main/java/com/example/`project name`/MyActivity.java

app/src/main/java/com/example/`project name`/MyActivity.java

app/src/main/java/com/example/`project name`/MyActivity.java