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

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

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

หมายเหตุ: สำหรับข้อมูลเกี่ยวกับการผสานรวมกับแพลตฟอร์มอื่นๆ หรือการใช้ IMA DAI SDK โปรดดู SDK โฆษณาสื่ออินเทอร์แอกทีฟ

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

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

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

หมายเหตุ: เนื่องจากส่วนขยาย ExoPlayer IMA จะรวม IMA SDK ไว้ในคู่มือนี้ด้วย กำลังใช้ทั้ง AdsRequest และ AdsManager อยู่ แต่ไม่ได้ใช้ ถูกเรียกอย่างชัดเจน

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

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

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

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

1. เริ่ม Android Studio
2. เลือกเริ่มโปรเจ็กต์ Android Studio ใหม่
3. ในหน้าเลือกโปรเจ็กต์ ให้เลือกเทมเพลตกิจกรรมที่ว่างเปล่า
4. คลิกถัดไป
5. ในหน้ากำหนดค่าโครงการ ให้ตั้งชื่อโครงการแล้วเลือกภาษา Java
   หมายเหตุ: IMA SDK ใช้ได้กับ Kotlin อย่างไรก็ตาม ตัวอย่างที่อธิบายในคู่มือนี้ใช้ Java
6. คลิกเสร็จสิ้น

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

ขั้นแรก ในไฟล์ build.gradle ระดับแอปพลิเคชัน ให้เพิ่มการนำเข้าสำหรับส่วนขยายลงในไฟล์ ทรัพยากร Dependency เนื่องจากส่วนขยาย ExoPlayer IMA มีขนาดใหญ่ คุณจึงเปิดใช้และเปิดใช้ 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 ของแอปเพื่อเปิดใช้การคลิกผ่านโฆษณา (ผู้ใช้ที่คลิกปุ่มดูข้อมูลเพิ่มเติม )

หมายเหตุ: 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

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. นำเข้าส่วนขยาย ExoPlayer IMA

เพิ่มข้อความการนำเข้าสำหรับส่วนขยาย 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 จากนั้นสร้าง 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. จัดการเหตุการณ์ของผู้เล่น

สุดท้าย ให้สร้าง Callback สำหรับเหตุการณ์ในวงจรของผู้เล่น

• onStart
• onResume
• onStop
• onPause
• onDestroy

หมายเหตุ: โค้ดตัวอย่างใช้ onStart/onStop สำหรับ SDK ของ Android เวอร์ชัน 24 ขึ้นไป และ onResume/onPause สำหรับเวอร์ชันก่อนหน้า 24

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