تُسهّل حزم تطوير البرامج لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك. ويمكن أن تطلب حزمة تطوير البرامج لإعلانات الوسائط التفاعلية إعلانات من أي خادم إعلانات متوافق مع نموذج عرض إعلانات الفيديو ويدير تشغيل الإعلانات في تطبيقاتك. باستخدام حزم تطوير البرامج لإعلانات الوسائط التفاعلية لـ AI، تقدم التطبيقات طلب بث فيديو ومحتوى مباشر، سواء من خلال الفيديوهات المسجّلة أو المحتوى المباشر. وستعرض حزمة تطوير البرامج (SDK) بعد ذلك بث فيديو مجمّعًا، بحيث لا تضطر إلى إدارة التبديل بين الإعلان والفيديو داخل التطبيق.
يوضّح هذا الدليل كيفية دمج حزمة تطوير البرامج لإعلانات الوسائط التفاعلية في تطبيق مشغّل فيديو بسيط. إذا كنت تريد الاطّلاع على عملية دمج النموذج أو إكمالها، عليك تنزيل BasicExample من GitHub.
نظرة عامة على عرض الإعلانات الديناميكية على شبكة البحث
ينفّذ تنفيذ DAI لإعلانات الوسائط التفاعلية أربعة مكوّنات رئيسية لحزمة تطوير البرامج (SDK)، وقد تم توضيحها في هذا الدليل:
StreamDisplayContainer: كائن حاوية يظهر فوق عنصر تشغيل الفيديو ويتضمّن عناصر واجهة مستخدم الإعلان.AdsLoader: كائن يطلب البث ويعالج الأحداث التي يتم تشغيلها من خلال كائنات الاستجابة لطلب البث. يجب إنشاء مثيل لأداة تحميل إعلانات واحدة فقط يمكن إعادة استخدامها طوال مدة التطبيق.StreamRequest: كائن يحدّد طلب البث. ويمكن أن تكون طلبات البث إما للفيديوهات المسجّلة أو أحداث البث المباشر. تحدد الطلبات معرّف المحتوى، فضلاً عن مفتاح واجهة برمجة التطبيقات أو الرمز المميز للمصادقة وغيرها من المعلمات.StreamManager: كائن يتعامل مع مصادر إدراج الإعلانات الديناميكية والتفاعلات مع خلفية DAI. يعالج مدير البث أيضًا إشعارات التتبُّع ويعيد توجيه أحداث البث والإعلانات إلى الناشر.
المتطلبات الأساسية
- استوديو Android
- تطبيق مشغّل الفيديو النموذجي الذي ستستخدمه لدمج حزمة تطوير البرامج (SDK)
تنزيل نموذج تطبيق مشغّل الفيديو وتشغيله
يوفّر نموذج التطبيق مشغّل فيديو صالحًا يشغّل فيديوهات وفق بروتوكول HLS. استخدِم هذا الإجراء كنقطة بداية لدمج وظيفة DAI في حزمة تطوير البرامج لإعلانات الوسائط التفاعلية.
- نزِّل نموذج تطبيق مشغّل فيديو ثم فكّ ضغطه.
- ابدأ تشغيل "استوديو Android" واختَر فتح مشروع حالي على "استوديو Android"، أو إذا كان "استوديو Android" قيد التشغيل حاليًا، اختَر ملف > جديد > استيراد مشروع. بعد ذلك، اختَر
SampleVideoPlayer/build.gradle. - شغِّل مزامنة Gradle من خلال اختيار الأدوات > Android > مزامنة المشروع مع ملفات Gradle.
- تأكّد من أنّ تطبيق المشغّل يجمّع ويعمل على جهاز Android فعلي أو جهاز افتراضي يعمل بنظام التشغيل Android باستخدام تشغيل > تشغيل "التطبيق". من الطبيعي أن يستغرق تحميل الفيديو بضع دقائق قبل تشغيله.
فحص نموذج مشغّل الفيديو
لا يحتوي نموذج مشغّل الفيديو على أي رمز دمج لحزمة تطوير البرامج لإعلانات الوسائط التفاعلية حتى الآن. يتكون نموذج التطبيق من جزأين رئيسيَّين:
samplevideoplayer/SampleVideoPlayer.java: مشغِّل HLS بسيط يستند إلى ExoPlayer ويشكّل أساس دمج "إعلانات الوسائط التفاعلية" (IMA)videoplayerapp/MyActivity.java- يؤدي هذا النشاط إلى إنشاء مشغّل الفيديو وتمريره إلىContextوSimpleExoPlayerView.
إضافة حزمة تطوير البرامج لإعلانات الوسائط التفاعلية من Android إلى تطبيق المشغّل
وعليك أيضًا تضمين مرجع إلى حزمة تطوير البرامج لإعلانات الوسائط التفاعلية. في "استوديو Android"، أضِف ما يلي إلى
ملف build.gradle على مستوى التطبيق، المتوفر في app/build.gradle:
repositories {
google()
jcenter()
}
dependencies {
implementation 'androidx.appcompat:appcompat:1.2.0'
implementation 'androidx.browser:browser:1.3.0'
implementation 'com.google.android.exoplayer:exoplayer:2.19.0'
implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.31.0'
}
نقطة التفتيش: يجب أن يتم تجميع التطبيق وتشغيله، ولكنك لم تُضِف إلى الآن عناصر أو رمز واجهة المستخدم لطلب الإعلانات وعرضها.
دمج حزمة تطوير البرامج لإعلانات الوسائط التفاعلية
-
أنشِئ صفًا جديدًا باسم
SampleAdsWrapperفي حزمةvideoplayerapp(فيapp/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) لالتفافSampleVideoPlayerالحالية وإضافة منطق التنفيذ الديناميكي لإدراج الإعلانات التفاعلية (DAI). ولإجراء ذلك، عليك أولاً إنشاءAdsLoader، الذي يُستخدم لطلب الإعلانات من خوادم الإعلانات.videoplayerapp/SampleAdsWrapper.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 { // Live stream 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 = "2528370"; 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للتمكّن من طلب البث باستخدام الإعلانات. إنّ أحداث البث المباشر هذه عبارة عن بث مباشر يتضمّن إعلانات (محدّد تلقائيًا) أو بث فيديو مسجَّل يعرض محتوًى مسجّلاً مسبقًا يعرض إعلانات. لتفعيل بث الفيديو المسجَّل، يجب التعليق على طلب البث المباشر وإلغاء تعليق طلب البث المسجَّل.videoplayerapp/SampleAdsWrapper.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); } } }); // Live stream 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 live stream to a VOD stream. // StreamRequest request = sdkFactory.createVodStreamRequest(TEST_CONTENT_SOURCE_ID, // TEST_VIDEO_ID, null, displayContainer); return request; } -
أنت بحاجة أيضًا إلى السمة
VideoStreamPlayerلتشغيل البث، لذا أضِف طريقةcreateVideoStreamPlayer()لإنشاء فئة مخفية الهوية تستخدم السمةVideoStreamPlayer.videoplayerapp/SampleAdsWrapper.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/SampleAdsWrapper.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/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); } } - يمكنك تعديل
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، من المحتمل أن هناك مشكلة في رمز دمج إعلانات الوسائط التفاعلية لتطبيقك. يمكنك مراجعة هذا الدليل ومستندات واجهة برمجة التطبيقات لاكتشاف أي اختلافات.
أما زلت تواجه المشاكل؟ يمكنك إدراج سطر في منتدى أداة تطوير البرامج لإعلانات الوسائط التفاعلية.