Bu sayfa, Cloud Translation API ile çevrilmiştir.

Android için IMA SDK ile özel reklam oynatma

Android için IMA SDK'yı uygulamanıza entegre etmenin en hızlı ve kolay yolu, SDK'nın tüm reklam oynatma mantığını işlemesini sağlarken uygulamanız da içerik videosu oynatmaya odaklanmasıdır. "SDK'ya ait reklam oynatma" adı verilen bu yaklaşım, Başlayın'daki varsayılan seçenektir.

Ancak video oynatıcınızda da reklam oynatmak isterseniz SDK bunun için bir arayüz sağlar. Bu yaklaşıma "özel reklam oynatma" diyoruz. Bu kılavuzun geri kalanında bu yaklaşımdan bahsedilmektedir.

Ön koşullar

Temel bir IMA entegrasyonu.

Şu anda temel bir IMA entegrasyonuna sahip değilseniz başlangıç noktası olarak GitHub'daki Gelişmiş Örneğe bakmanızı öneririz. Bu örnekte özel reklam oynatma zaten uygulanmaktadır. Bu kılavuzun geri kalanında, IMA reklamları ile özel reklam oynatma için gereken özellikler açıklanmaktadır.

VideoAdPlayer arayüzü

Özel reklam oynatma için uygulamanızın VideoAdPlayer arayüzünü uygulaması gerekir. Bu arayüz, SDK tarafından uygulamanıza reklam videoları oynatmasını bildirmek için kullanılır. Uygulamanız ayrıca bu arayüzü, SDK'yı önemli video reklam etkinlikleri hakkında bilgilendirmek için de kullanır. Arayüzü uygulamak için aşağıdaki adımları izleyin.

VideoAdPlayer Oluşturma

İlk adım, requestAds() ürününde anonim bir VideoAdPlayer sınıfı oluşturmaktır:

private VideoAdPlayer videoAdPlayer;
...

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

Video yöntemleri ekleme

Daha sonra, video oynatıcınıza reklam videolarını oynatmasını, yüklemesini, durdurmasını ve duraklatmasını söyleyen yöntemler ekleyin. Oynatıcıyı bırakma ve sesi alma yöntemleri de buraya eklenir:

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

Bu yöntemler, video oynatıcınızın kendi benzer yöntemlerini çevreleyen ince sarmalayıcılardır. Bu yöntemlerin, bir reklamın gösterilip gösterilmediğini izlemek için kullanılan dahili bir değişken ayarladığını unutmayın. Özel reklam oynatmada video oynatıcı hem içerik videosunu hem de video reklamları oynatır. Bu nedenle, hâlihazırda nelerin gösterildiğini takip etmeniz gerekir.

Reklam oynatma ilerleme durumu

VideoAdPlayer arayüzü başka bir arayüz (AdProgressProvider) uyguladığından bu arayüzü de uygulamanız gerekir. Yalnızca bir yöntem (getAdProgress()) vardır. Bu yöntem, SDK tarafından reklamların oynatma bilgilerini almak için kullanılır. Bunu anonim VideoAdPlayer sınıfınıza, diğer yöntemlerin altına ekleyin:

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(), videonun mevcut konumundan ve süresinden oluşması gereken bir VideoProgressUpdate türü döndürür. Oynatıcı reklamı oynatmıyorsa veya süre kullanılamıyorsa örnekte gösterildiği gibi VideoProgressUpdate.VIDEO_TIME_NOT_READY değerini döndürmesini sağlayın.

Video geri aramalarını yönetme

Özel reklam oynatma için uygulamanızın SDK'yı önemli video etkinlikleri hakkında bilgilendirmesi gerekir. SDK'ya göre bunlar, VideoAdPlayer.VideoAdPlayerCallback arayüzünde açıklanan geri çağırmalardır. Geri çağırma yöntemlerine geçmeden önce, SDK'nın isteği üzerine geri çağırma ekleyip kaldırabilmeniz gerekir. Bu işlem VideoAdPlayer içinde addCallback() ve removeCallback() kullanılarak yapılır:

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

Bu uygulama, List<>.add() ve remove() yöntemlerini çağıracağınız geri çağırmalar için bir List<> kullanır.

Geri aramaları çağırın

SDK'nın artık uygulamanıza geri çağırmalar ekleyip kaldırmasını söylemenin bir yolu olduğuna göre, geri çağırmanın çağrıldığı yerleri tanımlayın. Bir videoyu oynatma, duraklatma veya devam ettirme gibi büyük video etkinlikleri gerçekleştiğinde ya da bir video bittiğinde veya hata meydana geldiğinde uygulamanızın bu geri çağırmaları çağırması gerekir.

Bunu yapmak için SampleVideoPlayer öğesini, VideoFragment ürününden eklenen bu video etkinlikleri için bir işleyici olacak şekilde genişletin. SampleVideoPlayer içinde bu reklam geri çağırmalarını çağırmak için ayrı bir işleyici oluşturmak, SampleVideoPlayer ürününün reklamlar hakkında hiçbir şey bilmemesidir. Bu nedenle, video etkinliklerini reklamlarla işleyebilecek bir şeye yönlendirmeniz gerekir.

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

Başlatma, duraklatma ve devam ettirme

Oynatma durumunu takip etmek için yeni bir numaralandırma oluşturun ve SampleVideoPlayer içinde start() ile pause() yöntemleri için yeni geçersiz kılmalar ekleyin:

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

Hataları işleme

Video oynatıcının init() içinde ayarladığınız anonim hata işleyicisini geçersiz kılın:

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

Dinleyiciyi uygulamaya koyma

VideoFragment öğesine geri dönün ve SampleVideoPlayer örneğinize anonim bir OnVideoEventsListener ekleyin:

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

Bir reklam videosunun bittiği durumu işlemek için OnVideoCompletedListener öğesinin onVideoCompleted() yöntemini değiştirin:

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

İçerik ve reklamlar arasında geçiş yapma

Bu örnekte, hem içerik hem de reklamları oynatmak için aynı video oynatıcı örneği kullanılmaktadır. Bu nedenle, oynatıcınızdaki içerik ve reklamlar arasında geçiş yapmak için bazı mantık eklemeniz gerekir. Daha sonra, reklamın başladığı noktaya dönmek için içerik videosunu yeniden yükleyip bulabilirsiniz. Bunu yapmak için iki işlev ekleyin:

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

Bunlar, VideoFragment.onAdEvent() içinde sırasıyla CONTENT_PAUSE_REQUESTED ve CONTENT_RESUME_REQUESTED etkinlikleri alındığında çağrılır:

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

Özel reklam oynatmayı etkinleştir

Son adım, SDK'ya özel reklam oynatma kullandığınızı bildirmektir. Bu, AdDisplayContainer cihazınıza VideoAdPlayer geçirilerek yapılır:

adDisplayContainer.setPlayer(videoAdPlayer);

Oynatıcınızı setPlayer() adlı santrale geçirmeniz gerekiyor. Aksi takdirde SDK, SDK'ya ait oynatma özelliğini kullanır.

Bu kadar basit. IMA uygulamanıza özel reklam oynatma eklemek için gereken tüm adımlar bunlardır. Sorun yaşarsanız kendi uygulamanızı GitHub'daki Gelişmiş Örnek ile karşılaştırabilirsiniz.