כדי לדון במוצרים שלנו ולספק משוב, אפשר להצטרף לערוץ הרשמי של Ad Manager ב-Discord בשרת קהילת הפרסום והמדידה של Google.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

הגדרה עם DAI בשירות מלא

בחירת פלטפורמה: HTML5 Android iOS tvOS Cast Roku

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

סקירה כללית על IMA DAI

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

StreamDisplayContainer: אובייקט מאגר שנמצא מעל הרכיב של הפעלת הווידאו ומכיל את רכיבי ממשק המשתמש של המודעה.
AdsLoader: אובייקט שמבקש שידורים ומטפל באירועים שמופעלים על ידי אובייקטים של תגובה לבקשת שידור. צריך ליצור מופע של טוען מודעות אחד בלבד, שאפשר לעשות בו שימוש חוזר לאורך כל חיי האפליקציה.
StreamRequest: אובייקט שמגדיר בקשה לשידור. בקשות לשידור יכולות להיות לווידאו על פי דרישה (VOD) או לשידורים חיים. בבקשות לשידור חי מצוין מפתח נכס, ובבקשות ל-VOD מצוינים מזהה CMS ומזהה סרטון. שני סוגי הבקשות יכולים לכלול מפתח API שנדרש כדי לגשת לשידורים שצוינו, וקוד רשת של Google Ad Manager כדי ש-IMA SDK יטפל במזהי מודעות כפי שצוין בהגדרות של Google Ad Manager.
StreamManager: אובייקט שמטפל בסטרימינג של הטמעת מודעות דינמיות ובאינטראקציות עם הקצה העורפי של DAI. מנהל השידור גם מטפל בפינגים למעקב ומעביר אירועים של שידורים ומודעות לבעל האפליקציה.

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

Android Studio
אפליקציה לדוגמה של נגן וידאו לשילוב ה-SDK

הורדה והפעלה של האפליקציה לדוגמה של נגן הווידאו

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

מורידים את האפליקציה לדוגמה של נגן הווידאו ומחלצים אותה.
מפעילים את Android Studio ובוחרים באפשרות Open an existing Android Studio project (פתיחת פרויקט קיים ב-Android Studio). אם Android Studio כבר פועל, בוחרים באפשרות File > ‏New > ‏Import Project (קובץ > חדש > ייבוא פרויקט). ואז בוחרים באפשרות SampleVideoPlayer/build.gradle.
מריצים סנכרון של Gradle על ידי בחירה באפשרות Tools > Android > Sync Project with Gradle Files (כלים > Android > סנכרון הפרויקט עם קובצי Gradle).
מוודאים שאפליקציית הנגן עוברת הידור ופועלת במכשיר Android פיזי או במכשיר Android וירטואלי (AVD) באמצעות Run > Run 'app'. זה נורמלי שלוקח כמה רגעים עד שהווידאו נטען ומתחיל לפעול.

בדיקת נגן הווידאו לדוגמה

נגן הווידאו לדוגמה עדיין לא מכיל קוד שילוב של IMA DAI SDK. האפליקציה לדוגמה מורכבת משני חלקים עיקריים:

‫samplevideoplayer/SampleVideoPlayer.java: נגן HLS שמבוסס על ExoPlayer ומשמש כבסיס לשילוב של IMA DAI.
‫videoplayerapp/MyActivity.java: הפעילות הזו יוצרת את נגן הווידאו ומעבירה לו Context ו-media3.ui.PlayerView.

הוספת IMA DAI SDK לאפליקציית הנגן

צריך גם לכלול הפניה ל-IMA DAI SDK. ב-Android Studio, מוסיפים את הקוד הבא לקובץ build.gradle ברמת האפליקציה, שנמצא ב-app/build.gradle. כדי להשתמש ב-IMA SDK, צריך להפעיל את תהליך ההסרה של סוכר תחבירי בספרייה. לשם כך, צריך להגדיר את coreLibraryDesugaringEnabled true ולהוסיף את 'com.android.tools:desugar_jdk_libs' כיחסי תלות בקובץ build.gradle. פרטים נוספים זמינים במאמר ממשקי API של Java 11 ואילך שזמינים באמצעות הסרת סוכר תחבירי עם מפרט nio.

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.11.0"
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.21"))
    implementation("androidx.appcompat:appcompat:1.8.0")
    implementation("androidx.media3:media3-ui:$media3_version")
    implementation("androidx.media3:media3-exoplayer:$media3_version")
    implementation("androidx.media3:media3-exoplayer-hls:$media3_version")
    implementation("androidx.media3:media3-exoplayer-dash:$media3_version")
    implementation("androidx.mediarouter:mediarouter:1.8.1")
    implementation("com.google.ads.interactivemedia.v3:interactivemedia:3.40.0")
}build.gradle

שילוב של IMA DAI SDK

יוצרים מחלקה חדשה בשם SampleAdsWrapper בחבילה videoplayerapp (ב-app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) כדי לעטוף את SampleVideoPlayer הקיימת ולהוסיף לוגיקה שמטמיעה את IMA DAI. כדי לעשות את זה, קודם צריך ליצור AdsLoader שמשמש לבקשת השידור של DAI.

קטע הקוד הזה כולל פרמטרים לדוגמה ל-HLS ול-DASH, לשידורים חיים ולשידורי וידאו על פי דרישה (VOD). כדי להגדיר איזה שידור יופעל, מעדכנים את המשתנה CONTENT_TYPE.

package com.google.ads.interactivemedia.v3.samples.videoplayerapp;

import android.annotation.SuppressLint;
import android.content.Context;
import android.view.ViewGroup;
import android.webkit.WebView;
import androidx.annotation.Nullable;
import com.google.ads.interactivemedia.v3.api.AdErrorEvent;
import com.google.ads.interactivemedia.v3.api.AdEvent;
import com.google.ads.interactivemedia.v3.api.AdsLoader;
import com.google.ads.interactivemedia.v3.api.AdsManagerLoadedEvent;
import com.google.ads.interactivemedia.v3.api.CuePoint;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.StreamDisplayContainer;
import com.google.ads.interactivemedia.v3.api.StreamManager;
import com.google.ads.interactivemedia.v3.api.StreamRequest;
import com.google.ads.interactivemedia.v3.api.StreamRequest.StreamFormat;
import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate;
import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer.SampleVideoPlayerCallback;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;

/** This class adds ad-serving support to Sample HlsVideoPlayer */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class SampleAdsWrapper
    implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {

  // Live HLS stream asset key.
  private static final String TEST_HLS_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";

  // Live DASH stream asset key.
  private static final String TEST_DASH_ASSET_KEY = "PSzZMzAkSXCmlJOWDmRj8Q";

  // VOD HLS content source and video IDs.
  private static final String TEST_HLS_CONTENT_SOURCE_ID = "2548831";
  private static final String TEST_HLS_VIDEO_ID = "tears-of-steel";

  // VOD DASH content source and video IDs.
  private static final String TEST_DASH_CONTENT_SOURCE_ID = "2559737";
  private static final String TEST_DASH_VIDEO_ID = "tos-dash";

  private static final String NETWORK_CODE = "21775744923";

  private static final String PLAYER_TYPE = "DAISamplePlayer";

  private enum ContentType {
    LIVE_HLS,
    LIVE_DASH,
    VOD_HLS,
    VOD_DASH,
  }

  // Set CONTENT_TYPE to the associated enum for the stream type you would like to test.
  private static final ContentType CONTENT_TYPE = ContentType.VOD_HLS;

  /** Log interface, so we can output the log commands to the UI or similar. */
  public interface Logger {
    void log(String logMessage);
  }

  private final ImaSdkFactory sdkFactory;
  private AdsLoader adsLoader;
  private StreamManager streamManager;
  private final List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks;

  private final SampleVideoPlayer videoPlayer;
  private final Context context;
  private final ViewGroup adUiContainer;

  private String fallbackUrl;
  private Logger logger;

  /**
   * Creates a new SampleAdsWrapper that implements IMA direct-ad-insertion.
   *
   * @param context the app's context.
   * @param videoPlayer underlying HLS video player.
   * @param adUiContainer ViewGroup in which to display the ad's UI.
   */
  public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer, ViewGroup adUiContainer) {
    this.videoPlayer = videoPlayer;
    this.context = context;
    this.adUiContainer = adUiContainer;
    sdkFactory = ImaSdkFactory.getInstance();
    playerCallbacks = new ArrayList<>();
    createAdsLoader();
  }

  private void enableWebViewDebugging() {
    WebView.setWebContentsDebuggingEnabled(true);
  }

  private void createAdsLoader() {
    enableWebViewDebugging();
    VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer();
    StreamDisplayContainer displayContainer =
        ImaSdkFactory.createStreamDisplayContainer(adUiContainer, videoStreamPlayer);
    videoPlayer.setSampleVideoPlayerCallback(createSampleVideoPlayerCallback());
    adsLoader =
        sdkFactory.createAdsLoader(context, MyActivity.getImaSdkSettings(), displayContainer);
  }

  public void requestAndPlayAds() {
    adsLoader.addAdErrorListener(this);
    adsLoader.addAdsLoadedListener(this);
    adsLoader.requestStream(buildStreamRequest());
  }
SampleAdsWrapper.java

יוצרים שיטת עזר של createSampleVideoPlayerCallback() כדי לטפל ביצירת מופע של ממשק SampleVideoPlayerCallback שמרחיב את VideoStreamPlayer.VideoStreamPlayerCallback.

כדי לעבוד עם DAI, הנגן צריך להעביר אירועי ID3 ל-IMA DAI SDK. השיטה callback.onUserTextReceived() מבצעת את הפעולה הזו, בקוד לדוגמה הבא.

private SampleVideoPlayerCallback createSampleVideoPlayerCallback() {
  return new SampleVideoPlayerCallback() {
    @Override
    public void onUserTextReceived(String userText) {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onUserTextReceived(userText);
      }
    }

    @Override
    public void onSeek(int windowIndex, long positionMs) {
      // See if we would seek past an ad, and if so, jump back to it.
      long newSeekPositionMs = positionMs;
      if (streamManager != null) {
        CuePoint prevCuePoint = streamManager.getPreviousCuePointForStreamTimeMs(positionMs);
        if (prevCuePoint != null && !prevCuePoint.isPlayed()) {
          newSeekPositionMs = prevCuePoint.getStartTimeMs();
        }
      }
      videoPlayer.seekTo(windowIndex, newSeekPositionMs);
    }

    @Override
    public void onContentComplete() {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onContentComplete();
      }
    }

    @Override
    public void onPause() {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onPause();
      }
    }

    @Override
    public void onResume() {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onResume();
      }
    }

    @Override
    public void onVolumeChanged(int percentage) {
      for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
        callback.onVolumeChanged(percentage);
      }
    }
  };
}
SampleAdsWrapper.java

מוסיפים שיטת buildStreamRequest() כדי ליצור את ה-SteamRequest. השיטה הזו עוברת בין מקורות שונים בהתאם לאופן שבו מגדירים את המשתנה CONTENT_TYPE. השידור שמוגדר כברירת מחדל במדריך הזה הוא שידור VOD HLS לדוגמה של IMA.

@Nullable
private StreamRequest buildStreamRequest() {
  StreamRequest request;
  switch (CONTENT_TYPE) {
    case LIVE_HLS:
      // Live HLS stream request.
      return sdkFactory.createLiveStreamRequest(TEST_HLS_ASSET_KEY, null, NETWORK_CODE);
    case LIVE_DASH:
      // Live DASH stream request.
      return sdkFactory.createLiveStreamRequest(TEST_DASH_ASSET_KEY, null, NETWORK_CODE);
    case VOD_HLS:
      // VOD HLS request.
      request =
          sdkFactory.createVodStreamRequest(
              TEST_HLS_CONTENT_SOURCE_ID, TEST_HLS_VIDEO_ID, null, NETWORK_CODE);
      request.setFormat(StreamFormat.HLS);
      return request;
    case VOD_DASH:
      // VOD DASH request.
      request =
          sdkFactory.createVodStreamRequest(
              TEST_DASH_CONTENT_SOURCE_ID, TEST_DASH_VIDEO_ID, null, NETWORK_CODE);
      request.setFormat(StreamFormat.DASH);
      return request;
  }
  // Content type not selected.
  return null;
}
SampleAdsWrapper.java

צריך גם VideoStreamPlayer כדי להפעיל את הסטרימינג, אז מוסיפים את השיטה createVideoStreamPlayer(), שיוצרת מחלקה אנונימית שמטמיעה את VideoStreamPlayer.

private VideoStreamPlayer createVideoStreamPlayer() {
  return new VideoStreamPlayer() {
    @Override
    public void loadUrl(String url, List<HashMap<String, String>> subtitles) {
      videoPlayer.setStreamUrl(url);
      videoPlayer.play();
    }

    @Override
    public void pause() {
      // Pause player.
      videoPlayer.pause();
    }

    @Override
    public void resume() {
      // Resume player.
      videoPlayer.play();
    }

    @Override
    public int getVolume() {
      // Make the video player play at the current device volume.
      return 100;
    }

    @Override
    public void addCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
      playerCallbacks.add(videoStreamPlayerCallback);
    }

    @Override
    public void removeCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
      playerCallbacks.remove(videoStreamPlayerCallback);
    }

    @Override
    public void onAdBreakStarted() {
      // Disable player controls.
      videoPlayer.enableControls(false);
      log("Ad Break Started\n");
    }

    @Override
    public void onAdBreakEnded() {
      // Re-enable player controls.
      if (videoPlayer != null) {
        videoPlayer.enableControls(true);
      }
      log("Ad Break Ended\n");
    }

    @Override
    public void onAdPeriodStarted() {
      log("Ad Period Started\n");
    }

    @Override
    public void onAdPeriodEnded() {
      log("Ad Period Ended\n");
    }

    @Override
    public void seek(long timeMs) {
      // An ad was skipped. Skip to the content time.
      videoPlayer.seekTo(timeMs);
      log("seek");
    }

    @Override
    public VideoProgressUpdate getContentProgress() {
      return new VideoProgressUpdate(
          videoPlayer.getCurrentPositionMs(), videoPlayer.getDuration());
    }
  };
}
SampleAdsWrapper.java

מטמיעים את המאזינים הנדרשים ומוסיפים תמיכה בטיפול בשגיאות.

שימו לב להטמעה של AdErrorListener, כי היא קוראת לכתובת URL לגיבוי אם המודעות לא מופעלות. מכיוון שהתוכן והמודעות נמצאים בסטרימינג אחד, צריך להיות מוכנים להפעיל סטרימינג חלופי אם מתרחשת שגיאה בסטרימינג של DAI.

/** AdErrorListener implementation */
@Override
public void onAdError(AdErrorEvent event) {
  log(String.format("Error: %s\n", event.getError().getMessage()));
  // play fallback URL.
  log("Playing fallback Url\n");
  videoPlayer.setStreamUrl(fallbackUrl);
  videoPlayer.enableControls(true);
  videoPlayer.play();
}

/** AdEventListener implementation */
@Override
public void onAdEvent(AdEvent event) {
  switch (event.getType()) {
    case AD_PROGRESS:
      // Do nothing or else log will be filled by these messages.
      break;
    default:
      log(String.format("Event: %s\n", event.getType()));
      break;
  }
}

/** AdsLoadedListener implementation */
@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
  streamManager = event.getStreamManager();
  streamManager.addAdErrorListener(this);
  streamManager.addAdEventListener(this);
  streamManager.init();
}

/** Sets fallback URL in case ads stream fails. */
void setFallbackUrl(String url) {
  fallbackUrl = url;
}
SampleAdsWrapper.java

מוסיפים קוד לרישום ביומן.

/** Sets logger for displaying events to screen. Optional. */
void setLogger(Logger logger) {
  this.logger = logger;
}

private void log(String message) {
  if (logger != null) {
    logger.log(message);
  }
}SampleAdsWrapper.java

משנים את MyActivity ב-videoplayerapp כדי ליצור מופע ולקרוא ל-SampleAdsWrapper. בנוסף, צריך לשלוח קריאה ל-ImaSdkFactory.initialize() כאן באמצעות שיטת עזר כדי ליצור מכונה של ImaSdkSettings.

חשוב: כדי לשפר את זמני הטעינה של IMA, צריך להפעיל את השיטה ImaSdkFactory.initialize() בשלב מוקדם ככל האפשר במחזור החיים של האפליקציה. הפעלת השיטה בשלב מוקדם מאפשרת ל-IMA לטעון את המשאבים הנדרשים לפני הבקשה הראשונה לסטרימינג. הפעלת ה-method‏ ImaSdkFactory.initialize() מקבלת מופע של ImaSdkSettings. חשוב להשתמש באותם ערכי הגדרות כאן וכשיוצרים מכונה של AdsLoader. בדוגמה הזו נעשה שימוש ב-method העזר getImaSdkSettings() כדי לוודא שערכי ההגדרות זהים. מידע נוסף זמין במדריך לאופטימיזציה של זמן הטעינה של IMA.

package com.google.ads.interactivemedia.v3.samples.videoplayerapp;

import android.annotation.SuppressLint;
import android.app.Activity;
import android.content.res.Configuration;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.ImageButton;
import android.widget.ScrollView;
import android.widget.TextView;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;

/** Main Activity that plays media using {@link SampleVideoPlayer}. */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class MyActivity extends Activity {

  private static final String DEFAULT_STREAM_URL =
      "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";
  private static final String APP_LOG_TAG = "ImaDaiExample";
  private static final String PLAYER_TYPE = "DAISamplePlayer";
  private static ImaSdkSettings imaSdkSettings;

  protected SampleVideoPlayer sampleVideoPlayer;
  protected ImageButton playButton;

  private boolean contentHasStarted = false;

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

    // Initialize the IMA SDK as early as possible when the app starts. If your app already
    // overrides Application.onCreate(), call this method inside the onCreate() method.
    // https://developer.android.com/topic/performance/vitals/launch-time#app-creation
    ImaSdkFactory.getInstance().initialize(this, getImaSdkSettings());

    View rootView = findViewById(R.id.videoLayout);
    sampleVideoPlayer =
        new SampleVideoPlayer(rootView.getContext(), rootView.findViewById(R.id.playerView));
    sampleVideoPlayer.enableControls(false);
    playButton = rootView.findViewById(R.id.playButton);
    final SampleAdsWrapper sampleAdsWrapper =
        new SampleAdsWrapper(this, sampleVideoPlayer, rootView.findViewById(R.id.adUiContainer));
    sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL);

    final ScrollView scrollView = findViewById(R.id.logScroll);
    final TextView textView = findViewById(R.id.logText);

    sampleAdsWrapper.setLogger(
        logMessage -> {
          Log.i(APP_LOG_TAG, logMessage);
          if (textView != null) {
            textView.append(logMessage);
          }
          if (scrollView != null) {
            scrollView.post(() -> scrollView.fullScroll(View.FOCUS_DOWN));
          }
        });

    // Set up play button listener to play video then hide play button.
    playButton.setOnClickListener(
        view -> {
          if (contentHasStarted) {
            sampleVideoPlayer.play();
          } else {
            contentHasStarted = true;
            sampleVideoPlayer.enableControls(true);
            sampleAdsWrapper.requestAndPlayAds();
          }
          playButton.setVisibility(View.GONE);
        });
    orientVideoDescription(getResources().getConfiguration().orientation);
  }
MyActivity.java

מוסיפים את שיטת העזר getImaSdkSettings() כדי ליצור מופע של ImaSdkSettings.

public static ImaSdkSettings getImaSdkSettings() {
  if (imaSdkSettings == null) {
    imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
    imaSdkSettings.setPlayerType(PLAYER_TYPE);
    // Set any additional IMA SDK settings here.
  }
  return imaSdkSettings;
}MyActivity.java

משנים את קובץ הפריסה של הפעילות activity_my.xml כדי להוסיף רכיבים בממשק המשתמש לצורך רישום ביומן.

<!-- UI element for viewing SDK event log -->
<ScrollView
    android:id="@+id/logScroll"
    android:layout_width="match_parent"
    android:layout_height="0dp"
    android:layout_weight="0.5"
    android:padding="5dp"
    android:background="#DDDDDD">

    <TextView
        android:id="@+id/logText"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">
    </TextView>
</ScrollView>activity_my.xml

מזל טוב! עכשיו אתם יכולים לבקש ולהציג מודעות וידאו באפליקציה ל-Android. כדי לשפר את ההטמעה, כדאי לעיין בסימניות, בSnapback ובמאמרי העזרה של ה-API.

פתרון בעיות

אם נתקלתם בבעיות בהפעלת מודעת וידאו, נסו להוריד את BasicExample המלא. אם הוא פועל כמו שצריך ב-BasicExample, כנראה שיש בעיה בקוד השילוב של IMA באפליקציה.

אם הבעיות נמשכות, אפשר להיכנס לפורום של IMA SDK.