Android के लिए IMA SDK की मदद से, पसंद के मुताबिक विज्ञापन चलाना

Android के लिए IMA SDK को अपने ऐप्लिकेशन से इंटिग्रेट करने का सबसे तेज़ और आसान तरीका यह है कि SDK टूल, विज्ञापन दिखाने वाले सभी लॉजिक को हैंडल कर ले. वहीं, आपका ऐप्लिकेशन, कॉन्टेंट वीडियो चलाने पर फ़ोकस करता है. इस तरीके को "SDK टूल के मालिकाना हक वाले विज्ञापन वीडियो चलाना" कहा जाता है. यह शुरू करें में डिफ़ॉल्ट विकल्प है.

हालांकि, अगर आपको वीडियो प्लेयर में भी विज्ञापन चलाना है, तो SDK टूल इसका इंटरफ़ेस उपलब्ध कराता है. हम इस तरीके को "कस्टम विज्ञापन प्लेबैक" कहते हैं और इस गाइड के बाकी हिस्से में इसे लागू करने का तरीका बताया गया है.

ज़रूरी शर्तें

  • IMA का बुनियादी इंटिग्रेशन.

हमारा सुझाव है कि अगर आपके पास बुनियादी IMA इंटिग्रेशन नहीं है, तो शुरुआती पॉइंट के तौर पर GitHub पर बेहतर उदाहरण देखें. यह उदाहरण पहले से ही कस्टम विज्ञापन प्लेबैक लागू करता है. इस गाइड के बाकी हिस्से में, IMA विज्ञापनों के साथ कस्टम विज्ञापन प्लेबैक के लिए ज़रूरी सुविधाओं के बारे में बताया गया है.

VideoAdPlayer के साथ इंटरफ़ेस

पसंद के मुताबिक विज्ञापन चलाने के लिए, आपके ऐप्लिकेशन को VideoAdPlayer इंटरफ़ेस लागू करना होगा. SDK टूल इस इंटरफ़ेस का इस्तेमाल करके, आपके ऐप्लिकेशन को विज्ञापन वाले वीडियो चलाने की सूचना देता है. आपका ऐप्लिकेशन भी इसी इंटरफ़ेस का इस्तेमाल, SDK टूल को मुख्य वीडियो विज्ञापन इवेंट के बारे में बताने के लिए करता है. इंटरफ़ेस लागू करने के लिए, यह तरीका अपनाएं.

VideoAdPlayer बनाना

सबसे पहले, requestAds() में पहचान छिपाकर VideoAdPlayer क्लास बनाएं:

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 टूल के हिसाब से, ये ऐसे कॉलबैक होते हैं जिनकी जानकारी VideoAdPlayer.VideoAdPlayerCallback इंटरफ़ेस से दी जाती है. कॉलबैक मेथड का इस्तेमाल शुरू करने से पहले, आपके पास SDK टूल के अनुरोध पर कॉलबैक जोड़ने और हटाने की सुविधा होनी चाहिए. यह addCallback() और removeCallback() का इस्तेमाल करके, VideoAdPlayer में किया जाता है:

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);
}

शुरू करें, रोकें, और फिर से शुरू करें

वीडियो चलाने की स्थिति को ट्रैक करने के लिए, एक नया एनम बनाएं. साथ ही, SampleVideoPlayer में start() और pause() तरीकों के लिए, नए बदलाव जोड़ें:

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 पर वापस जाएं और अपने SampleVideoPlayer इंस्टेंस में, अपनी पहचान छिपाने वाला OnVideoEventsListener जोड़ें:

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();
            }
        }
    }
});

किसी विज्ञापन वीडियो ने जो केस लगाया है उसे हैंडल करने के लिए, OnVideoCompletedListener का onVideoCompleted() तरीका बदलें:

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;
}

इन्हें तब कॉल किया जाता है, जब VideoFragment.onAdEvent() में CONTENT_PAUSE_REQUESTED और CONTENT_RESUME_REQUESTED इवेंट मिलते हैं:

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

पसंद के मुताबिक विज्ञापन चलाने की सुविधा चालू करें

आखिरी कदम, SDK टूल को यह बताना कि आपके मुताबिक विज्ञापन चलाने की सुविधा का इस्तेमाल किया जा रहा है. ऐसा करने के लिए, आपके AdDisplayContainer में VideoAdPlayer पास किया जाता है:

adDisplayContainer.setPlayer(videoAdPlayer);

अपने प्लेयर को setPlayer() को पास करना ज़रूरी है. ऐसा न होने पर SDK टूल, SDK टूल के मालिकाना हक वाले वीडियो का इस्तेमाल करता है.

हो गया. ये सभी चरण आपके IMA इंप्लीमेंटेशन में कस्टम विज्ञापन प्लेबैक जोड़ने के लिए ज़रूरी हैं. अगर आपको कोई समस्या आती है, तो आप GitHub पर बेहतर उदाहरण से अपने खुद के लागू किए गए उदाहरण की तुलना कर सकते हैं.