تُسهل حزم تطوير البرامج لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك. ويمكن أن تطلب حِزم تطوير البرامج لإعلانات الوسائط التفاعلية إعلانات من أي خادم إعلانات متوافق مع VAST وإدارة تشغيل الإعلانات في تطبيقاتك. باستخدام حِزم تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية، تطلب التطبيقات بث الفيديو الإعلاني والمحتوى، سواء كان فيديو عند الطلب أو محتوى مباشرًا. وبعد ذلك، تعرض حزمة تطوير البرامج (SDK) بث فيديو مجمّعًا، حتى لا تضطر إلى إدارة التبديل بين الإعلان وفيديو المحتوى داخل تطبيقك.
اختيار حل DAI الذي يهمّك
إدراج إعلان ديناميكي لخدمة كاملة
يوضح هذا الدليل كيفية دمج حزمة تطوير البرامج لإعلانات الوسائط التفاعلية في تطبيق مشغِّل فيديو بسيط. إذا كنت ترغب في عرض أو متابعة نموذج دمج كامل، فيمكنك تنزيل BasicExample من GitHub.
نظرة عامة على إدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية
يتضمّن تنفيذ ميزة DAI لإعلانات الوسائط التفاعلية أربعة مكوّنات رئيسية لحزمة تطوير البرامج (SDK) كما هو موضّح في هذا الدليل:
StreamDisplayContainer: كائن حاوية يقع أعلى عنصر تشغيل الفيديو ويضمّ عناصر واجهة مستخدِم الإعلان.AdsLoader: عنصر يطلب ساحات المشاركات ويعالج الأحداث التي تم تشغيلها بواسطة عناصر الاستجابة لطلبات البث. ويجب إنشاء مثيل واحد فقط لأداة تحميل الإعلانات، والذي يمكن إعادة استخدامه طوال عمر التطبيق.StreamRequest: كائن يحدد طلب البث. ويمكن أن تكون طلبات البث مخصصة للفيديوهات المسجّلة أو المباشرة. تحدّد الطلبات معرّف محتوى، بالإضافة إلى مفتاح واجهة برمجة تطبيقات أو رمز مميّز للمصادقة ومعلَمات أخرى.StreamManager: عنصر يعالج مصادر بيانات إدراج الإعلانات الديناميكية والتفاعلات مع خلفية DAI. ويتعامل مدير البث أيضًا مع إشعارات التتبّع ويعيد توجيه أحداث البث والإعلانات إلى الناشر.
المتطلبات الأساسية
- استوديو Android
- نموذج تطبيق مشغّل فيديو لدمج حزمة تطوير البرامج (SDK)
تنزيل نموذج تطبيق مشغّل الفيديو وتشغيله
يوفّر نموذج التطبيق مشغّل فيديو يعمل بشكل صحيح ويشغّل فيديو HLS. استخدِم هذا الدليل كنقطة بداية لدمج إمكانات DAI في "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية" ضمن "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية" لنظام التشغيل Android.
نزِّل نموذج تطبيق مشغّل الفيديو واستخراجه.
شغِّل "استوديو Android" واختَر فتح مشروع حالي على "استوديو Android"، أو اختَر ملف > جديد > استيراد مشروع إذا كان "استوديو Android" قيد التشغيل. بعد ذلك، اختَر "
SampleVideoPlayer/build.gradle".شغِّل مزامنة Gradle من خلال اختيار الأدوات > Android > مشروع المزامنة مع ملفات Gradle.
تأكّد من أنّ تطبيق المشغّل يجمع ويشغِّل على جهاز Android فعلي أو جهاز Android افتراضي باستخدام تشغيل > تشغيل 'التطبيق'. من الطبيعي أن يستغرق تحميل الفيديو بضع لحظات قبل تشغيله.
الاطّلاع على نموذج مشغّل الفيديو
لا يحتوي نموذج مشغّل الفيديو على أي رمز دمج لأداة تطوير البرامج لإعلانات الوسائط التفاعلية حتى الآن. يتكوّن نموذج التطبيق من جزأين رئيسيين، هما:
samplevideoplayer/SampleVideoPlayer.java: مشغِّل HLS يستند إلى ExoPlayer ويعمل كأساس لدمج IMA DAI.videoplayerapp/MyActivity.java: يؤدي هذا النشاط إلى إنشاء مشغّل الفيديو ويعرض لهContextوSimpleExoPlayerView.
إضافة حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لنظام التشغيل Android إلى تطبيق المشغّل
يجب أيضًا تضمين مرجع إلى حزمة تطوير البرامج لإعلانات الوسائط التفاعلية. في "استوديو Android"، أضِف ما يلي إلى ملف build.gradle على مستوى التطبيق في app/build.gradle:
repositories {
google()
mavenCentral()
}
dependencies {
implementation 'androidx.appcompat:appcompat:1.6.1'
implementation 'androidx.media3:media3-exoplayer:1.3.1'
implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.33.0'
}
دمج حزمة تطوير البرامج لإعلانات الوسائط التفاعلية
أنشئ فئة جديدة باسم
SampleAdsWrapperفي حزمةvideoplayerapp(فيapp/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) لتضمينSampleVideoPlayerالحالية وإضافة منطق منطقي لتنفيذ DAI لإعلانات الوسائط التفاعلية. لإجراء ذلك، عليك أولاً إنشاء عنصرAdsLoaderيُستخدم لطلب الإعلانات من خوادم الإعلانات.videoplayerapp/عيّناتWrapper.java
package com.google.ads.interactivemedia.v3.samples.videoplayerapp; import android.annotation.TargetApi; import android.content.Context; import android.os.Build; import android.view.ViewGroup; import android.webkit.WebView; 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.ImaSdkSettings; 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.player.VideoProgressUpdate; import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer; import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer; import java.util.ArrayList; import java.util.HashMap; import java.util.List; public class SampleAdsWrapper implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener { // Livestream asset key. private static final String TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA"; // VOD content source and video IDs. private static final String TEST_CONTENT_SOURCE_ID = "2548831"; private static final String TEST_VIDEO_ID = "tears-of-steel"; private static final String PLAYER_TYPE = "DAISamplePlayer"; /** * Log interface, so you can output the log commands to the UI or similar. */ public interface Logger { void log(String logMessage); } private ImaSdkFactory sdkFactory; private AdsLoader adsLoader; private StreamDisplayContainer displayContainer; private StreamManager streamManager; private List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks; private SampleVideoPlayer videoPlayer; private Context context; private ViewGroup adUiContainer; private String fallbackUrl; private Logger logger; public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer, ViewGroup adUiContainer) { this.videoPlayer = videoPlayer; this.context = context; this.adUiContainer = adUiContainer; sdkFactory = ImaSdkFactory.getInstance(); playerCallbacks = new ArrayList<>(); createAdsLoader(); displayContainer = sdkFactory.createStreamDisplayContainer( this.adUiContainer, videoStreamPlayer ); } private void createAdsLoader() { ImaSdkSettings settings = new ImaSdkSettings(); adsLoader = sdkFactory.createAdsLoader(context); } public void requestAndPlayAds() { adsLoader.addAdErrorListener(this); adsLoader.addAdsLoadedListener(this); adsLoader.requestStream(buildStreamRequest()); } }أضِف طريقة
buildStreamRequest()إلىAdsLoaderحتى تتمكّن من طلب بث يتضمّن إعلانات. إنّه بث مباشر يتضمّن إعلانات (يتم ضبطه تلقائيًا) أو بث فيديو مسجّل(VOD) يعرض محتوى مسجَّلاً مسبقًا مع إعلانات. لتفعيل بث الفيديو عند الطلب، يُرجى التعليق على طلب البث المباشر وإلغاء التعليق عليه.لاستخدام ميزة DAI، يجب أن يمرّر المشغّل أحداث المعرّف 3 للبث المباشر إلى حزم تطوير البرامج لإعلانات الوسائط التفاعلية. في الرمز النموذجي التالي، يتم إجراء ذلك من خلال الطريقة
callback.onUserTextReceived().videoplayerapp/عيّناتWrapper.java
private StreamRequest buildStreamRequest() { VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer(); videoPlayer.setSampleVideoPlayerCallback( new SampleVideoPlayer.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 you would seek past an ad, and if so, jump back to it. long newSeekPositionMs = positionMs; if (streamManager != null) { CuePoint prevCuePoint = streamManager.getPreviousCuePointForStreamTime(positionMs / 1000); if (prevCuePoint != null && !prevCuePoint.isPlayed()) { newSeekPositionMs = (long) (prevCuePoint.getStartTime() * 1000); } } 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); } } }); // Livestream request. StreamRequest request = sdkFactory.createLiveStreamRequest( TEST_ASSET_KEY, null, displayContainer); // VOD request. Comment the createLiveStreamRequest() line above and uncomment this // createVodStreamRequest() below to switch from a livestream to a VOD stream. // StreamRequest request = sdkFactory.createVodStreamRequest(TEST_CONTENT_SOURCE_ID, // TEST_VIDEO_ID, null, displayContainer); return request; }تحتاج أيضًا إلى
VideoStreamPlayerلتشغيل البث، لذا أضِف طريقةcreateVideoStreamPlayer()لإنشاء صف بدون الكشف عن الهوية ينفِّذVideoStreamPlayer.videoplayerapp/عيّناتWrapper.java
private VideoStreamPlayer createVideoStreamPlayer() { VideoStreamPlayer player = new VideoStreamPlayer() { @Override public void loadUrl(String url, List<HashMap<String, String>> subtitles) { videoPlayer.setStreamUrl(url); videoPlayer.play(); } @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. videoPlayer.enableControls(true); log("Ad Break Ended\n"); } @Override public VideoProgressUpdate getContentProgress() { return new VideoProgressUpdate(videoPlayer.getCurrentPosition(), videoPlayer.getDuration()); } }; return player; }تنفيذ أدوات الاستماع المطلوبة وإضافة الدعم للتعامل مع الأخطاء.
يُرجى مراعاة تنفيذ علامة
AdErrorListener، لأنّها تستدعي عنوان URL احتياطيًا في حال تعذّر تشغيل الإعلانات. بما أنّ المحتوى والإعلانات يتم عرضها في بث واحد، يجب أن تكون جاهزًا للطلب ببث احتياطي إذا حدث خطأ في بث DAI.videoplayerapp/عيّناتWrapper.java
/** AdErrorListener implementation **/ @Override public void onAdError(AdErrorEvent event) { // play fallback URL. 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 are 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; }أضف رمزًا لتسجيل الدخول.
videoplayerapp/عيّناتWrapper.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); } }يمكنك تعديل
MyActivityفيvideoplayerappلإنشاء مثيل واستدعاءSampleAdsWrapper.videoplayerapp/MyActivity.java
import android.view.ViewGroup; import android.widget.ScrollView; ... public class MyActivity extends AppCompatActivity { ... @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_my); View rootView = findViewById(R.id.videoLayout); videoPlayer = new SampleVideoPlayer(rootView.getContext(), (SimpleExoPlayerView) rootView.findViewById(R.id.playerView)); videoPlayer.enableControls(false); final SampleAdsWrapper sampleAdsWrapper = new SampleAdsWrapper(this, videoPlayer, (ViewGroup) rootView.findViewById(R.id.adUiContainer)); sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL); final ScrollView scrollView = (ScrollView) findViewById(R.id.logScroll); final TextView textView = (TextView) findViewById(R.id.logText); sampleAdsWrapper.setLogger(new SampleAdsWrapper.Logger() { @Override public void log(String logMessage) { Log.i(APP_LOG_TAG, logMessage); if (textView != null) { textView.append(logMessage); } if (scrollView != null) { scrollView.post(new Runnable() { @Override public void run() { scrollView.fullScroll(View.FOCUS_DOWN); } }); } } }); playButton = (ImageButton) rootView.findViewById(R.id.playButton); // Set up play button listener to play video then hide play button. playButton.setOnClickListener(new View.OnClickListener() { @Override public void onClick(View view) { sampleAdsWrapper.requestAndPlayAds(); playButton.setVisibility(View.GONE); } }); } ... }عدّل ملف تنسيق النشاط
activity_my.xmlلإضافة عناصر واجهة المستخدم للتسجيل.res/layout/activity_my.xml
... <TextView android:id="@+id/playerDescription" android:text="@string/video_description" android:textAlignment="center" android:gravity="center_horizontal" android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="0.1" android:textSize="@dimen/font_size" /> <!-- 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> ...
تهانينا أنت الآن تطلب إعلانات فيديو وتعرضها في تطبيق Android. ولتحسين عملية التنفيذ، يمكنك الاطّلاع على الإشارات المرجعية وSnapback ومستندات واجهة برمجة التطبيقات.
تحديد المشاكل وحلّها
إذا كنت تواجه مشاكل في تشغيل إعلان فيديو، جرّب تنزيل BasicExample مكتملة. إذا كانت تعمل بشكل صحيح في BasicExample، من المحتمل أن تكون هناك مشكلة في رمز دمج إعلانات الوسائط التفاعلية لتطبيقك.
إذا كنت تواجه مشاكل إلى الآن، يُرجى زيارة منتدى حزمة تطوير البرامج لإعلانات الوسائط التفاعلية.