การเล่นโฆษณาที่กำหนดเองด้วย IMA SDK สำหรับ Android

เลิกใช้งานแล้ว: การเล่นโฆษณาที่กำหนดเองได้อธิบายถึงวิธีผสานรวม IMA ไว้ก่อนหน้านี้ SDK แยกต่างหากจาก "การเล่นโฆษณาที่ SDK เป็นเจ้าของ" "การเล่นโฆษณาที่ SDK เป็นเจ้าของ" เลิกใช้งานแล้ว เพื่อประโยชน์ของ ส่วนขยาย ExoPlayer-IMA ซึ่งเป็นวิธีผสานรวมที่ง่ายและรวดเร็ว IMA SDK สำหรับ Android ลงในแอปของคุณ ส่วนขยายและ SDK จะจัดการ ตรรกะการเล่นโฆษณา ในขณะที่แอปเน้นการเล่นวิดีโอเนื้อหา คู่มือเริ่มต้นใช้งาน IMA Android จะครอบคลุมการผสานรวม IMA ที่คล้ายกับการเล่นโฆษณาที่กำหนดเอง สามารถเล่นโฆษณาในวิดีโอเพลเยอร์ของตัวเองได้

ใน IMA v3.30.0 และเวอร์ชันที่ต่ำกว่า IMA SDK สามารถจัดการตรรกะของการเล่นโฆษณาทั้งหมดได้ ในขณะที่แอป โฟกัสไปที่การเล่นวิดีโอเนื้อหา วิธีการนี้เรียกว่า "การเล่นโฆษณาที่ SDK เป็นเจ้าของ"

หากต้องการเล่นโฆษณาในวิดีโอเพลเยอร์ SDK จะมีอินเทอร์เฟซสำหรับการดำเนินการดังกล่าว เราเรียกวิธีนี้ว่า "กำหนดเอง" การเล่นโฆษณา" และคำแนะนำส่วนที่เหลือจะพูดถึงการติดตั้งใช้งาน

ข้อกำหนดเบื้องต้น

• การผสานรวม IMA พื้นฐาน

เราขอแนะนำให้คุณดูที่ ตัวอย่างขั้นสูง บน GitHub เป็นจุดเริ่มต้นหากขณะนี้คุณไม่มี IMA พื้นฐาน การผสานรวม ตัวอย่างนี้ใช้การเล่นโฆษณาที่กำหนดเองอยู่แล้ว ส่วนที่เหลือ ของคู่มือนี้จะอธิบายคุณลักษณะที่จำเป็นสำหรับการเล่นโฆษณาแบบกำหนดเอง โฆษณา IMA

ประเด็นสำคัญ: ตัวอย่างพื้นฐาน จะใช้ ส่วนขยาย Exoplayer-IMA ซึ่งจะจัดการการตั้งค่าส่วนใหญ่ของ IMA SDK ด้วยเหตุนี้ ไม่สามารถใช้ตัวอย่างพื้นฐานเป็นจุดเริ่มต้นของคู่มือนี้ได้

อินเทอร์เฟซที่มี VideoAdPlayer

ในการเล่นโฆษณาที่กำหนดเอง แอปของคุณต้องใช้ VideoAdPlayer ของ Google 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();
        }
};

วิธีการเหล่านี้จะเป็น Wrapper ขนาดบางๆ รอบๆ โปรแกรมเล่นวิดีโอของคุณ โปรดทราบว่าวิธีการเหล่านี้จะตั้งค่าตัวแปรภายในที่ใช้ เพื่อติดตามว่าโฆษณาจะปรากฏหรือไม่ ในการเล่นโฆษณาที่กำหนดเอง โปรแกรมเล่นวิดีโอจะเล่นทั้งโฆษณาวิดีโอและเนื้อหา ดังนั้นคุณต้องรักษา แทร็กที่แสดงอยู่ในขณะนั้น

ความคืบหน้าในการเล่นโฆษณา

อินเทอร์เฟซ 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 นี่คือ Callback ที่ ตามที่อธิบายไว้ในอินเทอร์เฟซ VideoAdPlayer.VideoAdPlayerCallback ก่อนที่จะเข้าสู่เมธอด Callback คุณจะต้อง สามารถเพิ่มและนำ Callback ออกตามคำขอของ 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<> สำหรับ Callback ที่จะเรียกใช้ เมธอด List<>.add() และ remove()

โทรหา Callback

ตอนนี้ SDK มีวิธีบอกให้แอปเพิ่มและนำ Callback ออก กำหนดตำแหน่งที่มีการเรียก Callback แอปของคุณต้องเรียกใช้ Callback เหล่านี้เมื่อมีเหตุการณ์สำคัญทางวิดีโอเกิดขึ้น เช่น การเล่น การหยุดชั่วคราว การกลับมาเล่นต่อ หรือเมื่อวิดีโอเล่นจบหรือพบข้อผิดพลาด

โดยขยาย SampleVideoPlayer ให้มี Listener สำหรับรายการเหล่านี้ เหตุการณ์วิดีโอที่เพิ่มเข้ามาจาก VideoFragment เหตุผลที่ต้องทำให้ Listener แยกต่างหากใน SampleVideoPlayer เพื่อเรียก Callback ของโฆษณาเหล่านี้ นั่นเป็นเพราะ 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 ใหม่เพื่อติดตามสถานะการเล่นและเพิ่มการลบล้างใหม่ สำหรับเมธอด 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();
    }
}

จัดการข้อผิดพลาด

ลบล้าง Listener ข้อผิดพลาดที่ไม่ระบุชื่อของโปรแกรมเล่นวิดีโอที่คุณตั้งค่าไว้ใน 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;
}

ใช้งาน Listener

กลับไปยัง 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();
    }
}

สลับระหว่างเนื้อหากับโฆษณา

ตัวอย่างนี้ใช้โปรแกรมเล่นวิดีโออินสแตนซ์เดียวกันในการเล่นทั้ง 2 แบบ เนื้อหาและโฆษณา คุณจึงต้องเพิ่มตรรกะเพื่อสลับระหว่าง เนื้อหาและโฆษณาในโปรแกรมเล่นของคุณ คุณสามารถโหลดซ้ำและเรียกดู วิดีโอเนื้อหาเพื่อกลับไปยังจุดที่โฆษณาเริ่มต้น เพิ่ม 2 ทำหน้าที่นี้

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 หากพบปัญหา