راه اندازی IMA SDK برای DAI، راه اندازی IMA SDK برای DAI، راه اندازی IMA SDK برای DAI، راه اندازی IMA SDK برای DAI

IMA SDK ادغام تبلیغات چندرسانه ای را در وب سایت ها و برنامه های شما آسان می کند. IMA SDK می‌تواند از هر سرور تبلیغاتی سازگار با VAST آگهی درخواست کند و پخش آگهی را در برنامه‌های شما مدیریت کند. با IMA DAI SDK، برنامه‌ها درخواست پخش جریانی برای آگهی و ویدیوی محتوا را ارائه می‌کنند - اعم از VOD یا محتوای زنده. سپس SDK یک جریان ویدیوی ترکیبی را برمی‌گرداند، به طوری که نیازی به مدیریت جابجایی بین آگهی و ویدیوی محتوا در برنامه خود ندارید.

راه حل DAI مورد علاقه خود را انتخاب کنید

خدمات کامل DAI

این راهنما نحوه ادغام IMA DAI SDK را در یک برنامه پخش کننده ویدیوی ساده نشان می دهد. اگر می‌خواهید نمونه یکپارچه‌سازی کامل شده را مشاهده یا دنبال کنید، BasicExample را از GitHub دانلود کنید.

نمای کلی IMA DAI

پیاده سازی IMA DAI شامل چهار جزء اصلی SDK است که در این راهنما نشان داده شده است:

  • StreamDisplayContainer : یک شی کانتینری که در بالای عنصر پخش ویدیو قرار می گیرد و عناصر رابط کاربری تبلیغات را در خود جای می دهد.
  • AdsLoader : شی ای که درخواست جریان می کند و رویدادهای ایجاد شده توسط اشیاء پاسخ درخواست جریان را مدیریت می کند. شما باید فقط یک بارکننده تبلیغات را نمونه برداری کنید، که می تواند در طول عمر برنامه مجددا استفاده شود.
  • StreamRequest : یک شی که یک درخواست جریان را تعریف می کند. درخواست‌های جریان می‌تواند برای ویدیوی درخواستی یا پخش مستقیم باشد. درخواست‌های پخش زنده یک کلید دارایی را مشخص می‌کنند، در حالی که درخواست‌های VOD یک شناسه CMS و شناسه ویدیو را مشخص می‌کنند. هر دو نوع درخواست می‌توانند به صورت اختیاری شامل یک کلید API مورد نیاز برای دسترسی به جریان‌های مشخص شده، و یک کد شبکه Google Ad Manager برای IMA SDK برای مدیریت شناسه‌های تبلیغاتی که در تنظیمات Google Ad Manager مشخص شده‌اند، باشند.
  • StreamManager : شیئی که جریانهای درج آگهی پویا و تعاملات با باطن DAI را مدیریت می کند. مدیر جریان همچنین پینگ‌های ردیابی را مدیریت می‌کند و جریان‌ها و رویدادهای تبلیغاتی را به ناشر ارسال می‌کند.

پیش نیازها

نمونه برنامه پخش کننده ویدیو را دانلود و اجرا کنید

برنامه نمونه یک پخش کننده ویدیوی فعال را ارائه می دهد که ویدیوی HLS را پخش می کند. از این به عنوان نقطه شروع برای ادغام قابلیت‌های DAI IMA DAI SDK استفاده کنید.

  1. نمونه برنامه پخش ویدئو را دانلود کرده و آن را استخراج کنید.

  2. Android Studio را راه اندازی کنید و Open an Android Studio موجود را انتخاب کنید، یا اگر Android Studio از قبل در حال اجرا است، File > New > Import Project را انتخاب کنید. سپس SampleVideoPlayer/build.gradle را انتخاب کنید.

  3. با انتخاب Tools > Android > Sync Project with Gradle Files، همگام سازی Gradle را اجرا کنید.

  4. با استفاده از Run > Run 'app' اطمینان حاصل کنید که برنامه پخش کننده روی یک دستگاه Android فیزیکی یا یک دستگاه مجازی Android کامپایل و اجرا می شود. این طبیعی است که پخش جریانی ویدیو قبل از پخش چند لحظه طول بکشد تا بارگیری شود.

نمونه پخش کننده ویدیو را بررسی کنید

پخش‌کننده ویدیوی نمونه هنوز حاوی کد یکپارچه‌سازی IMA DAI SDK نیست. برنامه نمونه از دو بخش اصلی تشکیل شده است:

  1. samplevideoplayer/SampleVideoPlayer.java : یک پخش کننده HLS مبتنی بر ExoPlayer که به عنوان پایه ای برای ادغام IMA DAI عمل می کند.

  2. videoplayerapp/MyActivity.java : این اکتیویتی پخش کننده ویدیو را ایجاد می کند و به آن Context و media3.ui.PlayerView می دهد.

IMA DAI SDK را به برنامه پخش اضافه کنید

همچنین باید ارجاعی به IMA DAI SDK داشته باشید. در Android Studio، موارد زیر را به فایل build.gradle در سطح برنامه خود، واقع در app/build.gradle اضافه کنید. IMA SDK نیاز به حذف قند از کتابخانه دارد که باید با تنظیم coreLibraryDesugaringEnabled true و افزودن coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5' به عنوان یک وابستگی در فایل build.gradle این کار را انجام دهید. برای جزئیات بیشتر، Java 11+ APIهای موجود از طریق desugaring با مشخصات nio را ببینید. 

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.5.1"
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
    implementation 'androidx.appcompat:appcompat:1.7.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.7.0'
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.36.0'
build.gradle

IMA DAI SDK را یکپارچه کنید

  1. یک کلاس جدید به نام 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

  2. یک متد کمکی 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

  3. برای ایجاد SteamRequest یک متد buildStreamRequest() اضافه کنید. این روش بر اساس نحوه تنظیم متغیر 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

  4. شما همچنین به یک 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

  5. شنونده های مورد نیاز را پیاده سازی کنید و پشتیبانی برای مدیریت خطا اضافه کنید.

    به اجرای 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

  6. اضافه کردن کد برای ورود به سیستم 

    /** 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

  7. MyActivity در videoplayerapp برای نمونه‌سازی و فراخوانی SampleAdsWrapper تغییر دهید. همچنین، در اینجا با استفاده از روش کمکی برای ایجاد یک نمونه ImaSdkSettings ، با ImaSdkFactory.initialize() تماس بگیرید.

    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

  8. برای ایجاد یک نمونه ImaSdkSettings ، متد کمکی getImaSdkSettings() را اضافه کنید. 

    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

  9. برای افزودن عناصر رابط کاربری برای ثبت گزارش activity_my.xml فایل طرح‌بندی Activity را تغییر دهید. 

    <!-- 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 دیدن کنید.