تشغيل الإعلانات المخصّصة باستخدام حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لنظام التشغيل Android

في الإصدار 3.30.0 والإصدارات الأقدم لإعلانات الوسائط التفاعلية، يمكن لحزمة تطوير البرامج لإعلانات الوسائط التفاعلية معالجة كل منطق تشغيل الإعلانات، بينما يركّز تطبيقك على تشغيل فيديوهات المحتوى يسمى هذا النهج "تشغيل الإعلان باستخدام حزمة تطوير البرامج (SDK)"

إذا أردت تشغيل الإعلانات في مشغّل الفيديو، ستتغير حزمة SDK واجهة المستخدم لإجراء ذلك. نشير إلى هذا النهج على أنه "مخصص تشغيل الإعلان" ويتناول باقي هذا الدليل تنفيذه.

المتطلبات الأساسية

  • دمج أساسي لإعلانات الوسائط التفاعلية

ننصحك بالاطّلاع على مثال متقدم على GitHub كنقطة بداية إذا لم يكن لديك حاليًا إعلانات الوسائط التفاعلية الأساسية التكامل. ينفِّذ هذا المثال تشغيل الإعلان المخصّص. المتبقي في هذا الدليل الميزات اللازمة لتشغيل الإعلان المخصص باستخدام إعلانات الوسائط التفاعلية

الواجهة مع VideoAdPlayer

يتطلّب تشغيل الإعلان المخصّص تنفيذ تطبيقك VideoAdPlayer من واجهة pyplot. تستخدم حزمة تطوير البرامج (SDK) هذه الواجهة لإرسال إشعار إلى تطبيقك لتشغيل الإعلان. مقاطع الفيديو. يستخدم تطبيقك أيضًا هذه الواجهة لإبلاغ حزمة تطوير البرامج (SDK) بإعلان الفيديو الرئيسي. أحداث. اتّبِع الخطوات التالية لتنفيذ الواجهة.

إنشاء VideoAdPlayer

الخطوة الأولى هي إنشاء صف VideoAdPlayer مجهول الهوية. في requestAds():

private VideoAdPlayer videoAdPlayer;
...

private void requestAds(String adTagUrl) {
    videoAdPlayer = new VideoAdPlayer() {
    };
}

إضافة طرق للفيديوهات

بعد ذلك، إضافة طرق تطلب من مشغّل الفيديو تشغيل الإعلان وتحميله وإيقافه وإيقافه مؤقتًا مقاطع الفيديو. بالإضافة إلى ذلك، أضفنا طُرقًا لتحرير المشغّل والحصول على مستوى الصوت هنا:

videoAdPlayer = new VideoAdPlayer() {
        @Override
        public void playAd() {
            if (mIsAdDisplayed) {
                videoPlayer.resume();
            } else {
                isAdDisplayed = true;
                videoPlayer.play();
            }
        }

        @Override
        public void loadAd(String url) {
            isAdDisplayed = true;
            videoPlayer.setVideoPath(url);
        }
        @Override
        public void stopAd() {
            videoPlayer.stopPlayback();
        }
        @Override
        public void pauseAd() {
            videoPlayer.pause();
        }

        @Override
        public void release() {
            // any clean up that needs to be done
        }

        @Override
        public int getVolume() {
            return videoPlayer.getVolume();
        }
};

تمثّل هذه الأساليب أغلفة رفيعة حول محتوى مشابه لمشغّل الفيديو الطرق. لاحظ أن هذه الطرق تحدد متغيرًا داخليًا يُستخدم لتتبُّع ما إذا كان سيتم عرض الإعلان أم لا. عند تشغيل الإعلان المخصّص يشغّل مشغّل الفيديو كلاً من إعلانات الفيديو وإعلانات الفيديو، لذا تحتاج إلى الذي يتم عرض مساره حاليًا.

مستوى تقدّم تشغيل الإعلان

تنفِّذ الواجهة VideoAdPlayer واجهة أخرى، AdProgressProvider، لذا يجب تنفيذها أيضًا. تحتوي فقط على إحدى الطرق، وهي getAdProgress()، وتستخدمها حزمة SDK للحصول على معلومات التشغيل للإعلانات. أضِفه إلى جهازك المجهول VideoAdPlayer ، أسفل الطرق الأخرى:

VideoAdPlayer videoAdPlayer = new VideoAdPlayer() {
        ...
        @Override
        public VideoProgressUpdate getAdProgress() {
            if (!isAdDisplayed || videoPlayer.getDuration() <= 0) {
                return VideoProgressUpdate.VIDEO_TIME_NOT_READY;
            }
            return new VideoProgressUpdate(videoPlayer.getCurrentPosition(),
                    videoPlayer.getDuration());
        }
};

تعرض الدالة getAdProgress() النوع VideoProgressUpdate، موضع الفيديو الحالي ومدته إذا كان المشغّل لا يعرض إعلانًا أو إذا كانت المدة غير متاحة، اطلب عرضه VideoProgressUpdate.VIDEO_TIME_NOT_READY كما هو موضّح في المثال.

إدارة استدعاءات الفيديو

يتطلّب تشغيل الإعلان المخصّص من تطبيقك تزويد حزمة تطوير البرامج (SDK) بحزمة تطوير البرامج (SDK) الرئيسية أحداث الفيديو. ووفقًا لحزمة SDK، تكون هذه الاستدعاءات عبارة عن الموضحة في واجهة VideoAdPlayer.VideoAdPlayerCallback. قبل الدخول في طرق معاودة الاتصال نفسها، ينبغي أن تكون إضافة طلبات معاودة الاتصال وإزالتها بناءً على طلب حزمة تطوير البرامج (SDK). هذا هو تم داخل VideoAdPlayer باستخدام addCallback() وremoveCallback():

private List<VideoAdPlayerCallback> adCallbacks = new ArrayList<>(1);

VideoAdPlayer videoAdPlayer = new VideoAdPlayer() {
        ...
        @Override
        public void addCallback(VideoAdPlayerCallback videoAdPlayerCallback) {
            adCallbacks.add(videoAdPlayerCallback);
        }

        @Override
        public void removeCallback(VideoAdPlayerCallback videoAdPlayerCallback) {
            adCallbacks.remove(videoAdPlayerCallback);
        }
};

تستخدم عملية التنفيذ هذه List<> لاستدعاءات الاستدعاء المطلوب استدعاءها. الطريقتان List<>.add() وremove().

الاتصال بجهات معاودة الاتصال

والآن بعد أن أصبح لدى SDK طريقة لتطلب من تطبيقك إضافة استدعاءات وإزالتها، تحدد الأماكن التي يتم استدعاء فيها. يحتاج تطبيقك إلى الاتصال عمليات الاستدعاء هذه عند وقوع أحداث فيديو مهمة، مثل التشغيل أو الإيقاف المؤقت أو استئنافه، أو عند انتهاء الفيديو أو حدوث خطأ.

لإجراء ذلك، يجب توسيع نطاق SampleVideoPlayer ليتم الاستماع إلى هذه المقاطع. أحداث الفيديو التي تمت إضافتها من VideoFragment. سبب إجراء مستمِع منفصل في SampleVideoPlayer لاستدعاء طلبات معاودة الاتصال بهذه الإعلانات هو أن SampleVideoPlayer لا يعرف أي شيء عن الإعلانات، لذا، عليك إعادة توجيه أحداث الفيديو إلى عنصر يمكنه التعامل مع الإعلانات.

public interface OnVideoEventsListener {
    void onPlay();
    void onResume();
    void onPause();
    void onError();
}

private final List<OnVideoEventsListener> onVideoEventsListeners = new ArrayList<>(1);

public void addVideoEventsListener(OnVideoEventsListener listener) {
    onVideoEventsListeners.add(listener);
}

البدء والإيقاف المؤقت والاستئناف

أنشِئ تعدادًا جديدًا لتتبُّع حالة التشغيل وإضافة عمليات إلغاء جديدة. للطريقتين start() وpause() في SampleVideoPlayer:

private enum PlaybackState {
    STOPPED, PAUSED, PLAYING
}

private PlaybackState playbackState = PlaybackState.STOPPED;

@Override
public void start() {
    super.start();
    switch (playbackState) {
        case STOPPED:
            for (OnVideoEventsListener listener : onVideoEventsListeners) {
                listener.onPlay();
            }
            break;
        case PAUSED:
            for (OnVideoEventsListener listener : onVideoEventsListeners) {
                listener.onResume();
            }
            break;
        default:
            // Already playing; do nothing.
            break;
    }
    playbackState = PlaybackState.PLAYING;
}

@Override
public void pause() {
    super.pause();
    playbackState = PlaybackState.PAUSED;
    for (OnVideoEventsListener listener : onVideoEventsListeners) {
        listener.onPause();
    }
}

التعامل مع الأخطاء

تجاهُل أداة معالجة الأخطاء المجهولة التي ضبطتها في init() لمشغّل الفيديو:

@Override
public boolean onError(MediaPlayer mp, int what, int extra) {
    playbackState = PlaybackState.STOPPED;
    for (OnVideoEventsListener listener : onVideoEventsListeners) {
        listener.onError();
    }

    // Returning true signals to MediaPlayer that the error was handled.
    // This  prevents the completion handler from being called.
    return true;
}

تنفيذ أداة الاستماع

الرجوع إلى VideoFragment وإضافة OnVideoEventsListener مجهول إلى مثيل SampleVideoPlayer:

mVideoPlayer.addVideoEventsListener(new OnVideoEventsListener() {
    @Override
    public void onPlay() {
        if (isAdDisplayed) {
            for (VideoAdPlayerCallback callback : adCallbacks) {
                callback.onPlay();
            }
        }
    }

    @Override
    public void onResume() {
        if (isAdDisplayed) {
            for (VideoAdPlayerCallback callback : adCallbacks) {
                callback.onResume();
            }
        }
    }

    @Override
    public void onPause() {
        if (isAdDisplayed) {
            for (VideoAdPlayerCallback callback : adCallbacks) {
                callback.onPause();
            }
        }
    }

    @Override
    public void onError() {
        if (isAdDisplayed) {
            for (VideoAdPlayerCallback callback : adCallbacks) {
                callback.onError();
            }
        }
    }
});

تغيير طريقة onVideoCompleted() من OnVideoCompletedListener للتعامل مع حالة انتهاء فيديو الإعلان:

public void onVideoCompleted() {
    // Handle completed event for playing post-rolls.
    if (isAdDisplayed) {
        for (VideoAdPlayerCallback callback : adCallbacks) {
            callback.onEnded();
        }
    } else {
        if (adsLoader != null) {
            adsLoader.contentComplete();
    }
}

التبديل بين المحتوى والإعلانات

يستخدم هذا المثال مثيل مشغّل الفيديو نفسه لتشغيل كليهما والمحتوى والإعلانات، لذا يجب عليك إضافة بعض المنطق للتبديل بين المحتوى والإعلانات في المشغّل. يمكنك بعد ذلك إعادة التحميل وتقديم في شبكة المحتوى للعودة إلى نقطة بداية الإعلان. إضافة اثنين المختلفة للقيام بذلك:

private int savedContentPosition = 0;

private void pauseContent() {
    savedContentPosition = videoPlayer.getCurrentPosition();
    videoPlayer.stopPlayback();
    isAdDisplayed = true;
}

private void resumeContent() {
    videoPlayer.setVideoPath(getString(R.string.content_url));
    videoPlayer.seekTo(mSavedContentPosition);
    videoPlayer.play();
    isAdDisplayed = false;
}

وتسمى هذه الطرق عندما يكون CONTENT_PAUSE_REQUESTED تم استلام CONTENT_RESUME_REQUESTED أحداث، في VideoFragment.onAdEvent()، على التوالي:

case CONTENT_PAUSE_REQUESTED:
    pauseContent();
    break;
case CONTENT_RESUME_REQUESTED:
    resumeContent();
    break;

تفعيل تشغيل الإعلان المخصّص

الخطوة الأخيرة هي إعلام حزمة SDK بأنّك تستخدم تشغيل الإعلان المخصّص. يتم ذلك من خلال تمرير VideoAdPlayer إلى AdDisplayContainer:

adDisplayContainer.setPlayer(videoAdPlayer);

من الضروري تمرير اللاعب إلى setPlayer(). بخلاف ذلك، سيتم تستخدم حزمة SDK عملية تشغيل تملكها حزمة SDK.

ما مِن إجراءات أخرى مطلوبة. هذه هي جميع الخطوات اللازمة لإضافة تشغيل إعلان مخصّص إلى تنفيذ إعلانات الوسائط التفاعلية يمكنك مقارنة عملية التنفيذ الخاصة بك مع مثال متقدم على GitHub إذا واجهت مشكلة.