הפעלת מודעות בהתאמה אישית באמצעות IMA SDK ל-Android

ב-IMA SDK מגרסה 3.30.0 ומטה, ה-IMA SDK יכול לטפל בכל הלוגיקה של הפעלת מודעות. בזמן שהאפליקציה מתמקדת בהפעלת סרטון תוכן. הגישה הזאת נקראת 'הפעלת מודעה בבעלות SDK'.

כדי להציג מודעות בנגן הווידאו, צריך להתקין את ערכת ה-SDK מספקת ממשק בשביל זה. אנחנו מתייחסים לגישה הזו כאל הפעלת מודעה" ושאר המדריך הזה יוסבר איך להטמיע אותו.

דרישות מוקדמות

  • שילוב בסיסי של IMA.

מומלץ לעיין דוגמה מתקדמת ב-github כנקודת התחלה, אם אין לך כרגע IMA בסיסי של Google Analytics. הדוגמה הזו כבר כוללת הפעלה של מודעות בהתאמה אישית. היתרה במדריך זה יתוארו התכונות הנחוצות להפעלת מודעה מותאמת אישית עם מודעות IMA.

ממשק עם VideoAdPlayer

כדי להפעיל מודעות בהתאמה אישית, האפליקציה צריכה להטמיע את VideoAdPlayer גרפי. הממשק הזה משמש את ה-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();
        }
};

השיטות האלה הן wrappers דקים סביב האלמנטים דומים של נגן הווידאו שיטות. לתשומת ליבכם: השיטות האלה מגדירות משתנה פנימי שנמצא בשימוש כדי לעקוב ולראות אם מודעה מוצגת. בהפעלה של מודעה בהתאמה אישית, נגן הווידאו מפעיל גם מודעות וידאו וגם מודעות וידאו, לכן צריך שלגביו מוצג כרגע.

התקדמות הפעלת המודעה

בממשק VideoAdPlayer מוטמע ממשק אחר, AdProgressProvider, לכן צריך להטמיע גם אותו. יש בו רק שיטה אחת, getAdProgress(), שבה ה-SDK משתמש כדי לקבל מידע על הפעלת מודעות. ניתן להוסיף אותה אל VideoAdPlayer בעילום שם class, מתחת לשיטות האחרות:

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, אלו קריאות חוזרות (callback) שמתוארים בממשק של 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 אפשרות להורות לאפליקציה להוסיף ולהסיר קריאות חוזרות, מגדירים את המקומות שבהם תתבצע קריאה חוזרת (callback). האפליקציה צריכה להתקשר הקריאות החוזרות האלה כשמתרחשים אירועי וידאו משמעותיים, כמו הפעלה, השהיה או שניתן להמשיך לצפות בסרטון, או כשסרטון מסתיים או נתקלת בשגיאה.

לשם כך, אפשר להרחיב את SampleVideoPlayer כדי לקבל האזנה להקלטות האלה. אירועי וידאו שנוספו מ-VideoFragment. הסיבה לכך מאזינים נפרדים ב-SampleVideoPlayer כדי לקרוא לקריאות החוזרות (callbacks) האלה של המודעה כי ל-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);
}

התחלה, השהיה והמשך

אפשר ליצור enum חדש כדי לעקוב אחרי מצב ההפעלה ולהוסיף שינויים חדשים מברירת המחדל ל-methods 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.

זה הכול. אלה כל השלבים הנדרשים כדי להוסיף הפעלה של מודעה בהתאמה אישית אל הטמעת IMA. תוכלו להשוות בין ההטמעות שלכם דוגמה מתקדמת ב-github אם אתם נתקלים בבעיה.