תחילת השימוש בתוסף IMA של Exoplayer

ערכות IMA SDK מאפשרות לכם לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות שלכם. ערכות IMA SDK יכולות לבקש מודעות מכל שרת מודעות שתואם ל-VAST ולנהל את הפעלת המודעות באפליקציות שלכם. בעזרת ערכות SDK בצד הלקוח של IMA, יש לך שליטה על הפעלת סרטונים בתוכן, בזמן שה-SDK מטפל בהפעלת המודעות. המודעות מופעלות נגן וידאו נפרד שממוקם מעל נגן הווידאו של התוכן של האפליקציה.

במדריך הזה נדגים איך לשלב את IMA SDK בפרויקט ריק ב-Android Studio באמצעות תוסף IMA של ExoPlayer. אם אתם רוצים להציג שילוב לדוגמה שהושלם או לעקוב אחריו, אפשר להוריד את BasicExample מ-GitHub.

סקירה כללית בצד הלקוח של IMA

ההטמעה של IMA בצד הלקוח כוללת ארבעה רכיבי SDK עיקריים, שמודגמים בתהליך guide:

  • AdDisplayContainer: אובייקט מאגר תגים שבו מתבצעות מודעות.
  • AdsLoader: אובייקט ששולח מודעות ומטפל באירועים מתגובות לבקשות להצגת מודעות. צריך רק ליצור טוען מודעות אחד, שניתן להשתמש בו שוב במהלך חיי האפליקציה.
  • AdsRequest: אובייקט שמגדיר בקשה להצגת מודעות. בקשות להצגת מודעות מציינות את כתובת ה-URL של תג המודעה מסוג VAST, וגם פרמטרים נוספים, כמו מאפייני מודעה.
  • AdsManager: אובייקט שמכיל את התגובה לבקשה להצגת מודעה, שולט בהפעלת המודעה ומאזינים למודעה אירועים שהופעלו על ידי ה-SDK.

דרישות מוקדמות

לפני שמתחילים, צריך Android Studio 3.0 ואילך.

1. יצירת פרויקט חדש של Android Studio

כדי ליצור פרויקט ב-Android Studio, מבצעים את השלבים הבאים:

  1. מפעילים את Android Studio.
  2. בוחרים באפשרות התחלת פרויקט חדש של Android Studio.
  3. בדף Choose your project, בוחרים את התבנית Empty Activity.
  4. לוחצים על הבא.
  5. בדף Configure your project, נותנים שם לפרויקט ובוחרים ב-Java לשפה.
  6. לוחצים על סיום.

2. הוספת תוסף IMA של ExoPlayer לפרויקט

קודם כול, מוסיפים את הייבוא של התוסף בקובץ 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. הוספה של קטע הקוד הבא אל את קובץ המניפסט של האפליקציה כדי לאפשר קליקים על מודעות (משתמשים שלוחצים על למידע נוסף) ). 
  <?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. יוצרים מאגר תגים בממשק המשתמש של המודעות

אפשר ליצור את התצוגה שתשמש כ-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. ייבוא תוסף 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. לאחר מכן, יוצרים את 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.