Zucks Ad Network Android用SDK導入手順

対象OS

Android 4.1 以上

更新履歴

2021/02/16 v4.8.4 一部の動画を含む広告で、表示が乱れる問題を修正

2020/02/03 v4.8.3 内部処理の軽微な変更

2020/12/09 v4.8.2 Android版MoPubメディエーションアダプタ v4.8.3.0をサポート

2020/11/12 v4.8.1 リワード広告において一部クリエイティブ表示時にクラッシュする問題を修正

2020/10/29 v4.8.0

  • リワード広告に対応
  • 内部処理を複数モジュールによるライブラリ構成に変更

2020/07/30 v4.7.0

  • targetSdkVersionを28に変更
  • play-services-baseへの依存を削除
  • play-services-ads-identifier v16.0.0以上を内部的に利用するよう変更
  • Zucks Ad Network SDK向けProguard設定ファイルを同梱するよう変更
  • SDK配布方式をMaven経由でのaar形式ライブラリのみに変更

2018/03/28 v4.6.1 ビューアブル状態による動画広告の自動再生と一時停止に対応

2017/08/14 v4.6.0 ライブラリの更新

2017/06/28 v4.5.2 ライブラリの更新

2017/06/02 v4.5.1 不要なファイルの削除

2017/06/01 v4.5.0 ネイティブ広告の追加

2017/03/03 v4.4.2 MoPubメディエーション用アダプタに対応

2017/02/23 v4.4.1 全画面インライン広告のフォアグラウンド復帰時再ロード処理を廃止

2017/01/10 v4.4.0 全画面(縦)広告の追加

2016/12/07 v4.3.3 特定の環境でバナー広告がクラッシュする不具合修正

2016/11/11 v4.3.2 バナー広告の不具合修正

2016/09/12 v4.3.1 iマークタップ時のコールバック呼び出しを変更

2016/07/07 v4.3.0 Unity Plugin対応

2016/06/22 v4.2.2 バナー広告の不具合修正

2016/06/15 v4.2.1 バナー広告(AdMobメディエーション導入時)の不具合修正

2016/05/27 v4.2.0 AdMobメディエーション対応、バナーのコールバックを追加

2016/05/25 v4.1.1 インタースティシャル広告の不具合修正

2016/05/19 v4.1.0 バナー広告サイズアジャスト機能の追加

2016/02/16 v4.0.0 設計の見直し、インタースティシャル広告表示の高速化

SampleAppダウンロード

SDK組み込み済みの実装サンプルアプリをダウンロードできます。
下記導入手順と合わせて実装時の参考にお使いください。

SampleAppをダウンロード

1. プロジェクトへの導入

ⅰ. build.gradleの設定

プロジェクトでGradleを利用している場合、build.gradleに下記の設定を追加してください。

Zucks Ad Network Android用SDKはv4.7.0以降より、Maven経由での配布のみのサポートになりました。

ダウンロードが必要な場合(旧バージョン v4.6.1 のダウンロード)

ⅰ. SDKファイルのダウンロード

下記よりv4.6.1のSDK一式をダウンロードしてください。

SDK(v4.6.1)ダウンロード

ⅱ. jarファイルのプロジェクトへの追加

ZucksAdNetworkSDK-4.x.x.jarをプロジェクト内のlibsフォルダに配置します。

AndroidStudio

ⅲ. Gradleによるプロジェクト更新

build.gradleに下記の設定を追加します。※既に記載されている場合は不要です。

Sync Project with Gradle Files を押下し、プロジェクト設定を更新します。

AndroidStudio

マニフェストの設定

パーミッションの追加

AndroidManifest.xmlに、下記の<uses-permission>タグを記述してください。
既にアプリで設定済みの場合は、追加で記述する必要はありません。

  • INTERNET : ネットワーク経由で広告を取得するために利用します。
  • ACCESS_NETWORK_STATE : ネットワーク状態を取得するために利用します。

2. Google Play Servicesの導入

v4.7.0以降、この手順は不要になりました。

v4.7.0未満をお使いの場合

ⅰ. Google Play Servicesのインストール

1. Google Play Servicesのインストールをする場合、build.gradleに下記の設定を追加してください。

2. AndroidManifest.xml<application>タグ内に、下記の<meta-data>タグを記述してください。

3. 広告の表示設定

広告タイプの選択

下記より掲載する広告タイプを選択して、続きの実装方法をご確認ください。

ⅰ. バナー広告

アプリ内にバナー広告を表示します。

バナー広告のリフレッシュ間隔設定は管理画面より行います。

バナー広告表示例(320x50)

バナー広告表示例(320x50)

バナー広告の表示

広告表示を行いたい任意のレイアウトファイルにnet.zucks.view.AdBannerを追加してください。
その際、レイアウトパラメータにFrame IDを指定してください。

アプリケーション内で下記の手順でnet.zucks.view.AdBannerのインスタンスを生成し、レイアウトに追加してください。
その際、第二引数にFrame IDを指定してください。

以上でバナー広告の設置が完了しました。アプリを起動し広告の表示を確認してください。

広告コールバック

Javaコードで実装する場合、net.zucks.listener.AdBannerListenerを使用して、広告情報のロード時や広告タップ時のコールバックを受け取ることが可能です。

実装例は以下の通りです。

検知できるコールバック一覧は以下の通りです。

public void onReceiveAd(AdBanner adBanner) 広告情報のロード成功時に通知されます。
リフレッシュ間隔を設定している場合はリフレッシュ毎に通知されます。
public void onTapAd(AdBanner adBanner) 広告タップ時に通知されます。
public void onFailure(AdBanner adBanner, Exception e) 広告情報のロード失敗時に通知されます。
エラーの内容によって以下のExceptionが設定されます。
net.zucks.exception.NetworkNotFoundException
→ オフラインエラー
net.zucks.exception.FrameIdNotFoundException
→ Frame IDエラー
net.zucks.exception.DisplaySizeTooSmallException
→ 画面サイズエラー
net.zucks.exception.ParentNotFoundException
→ 親Viewが存在していないエラー net.zucks.exception.AdIllegalStateException
→ 広告ステータス異常エラー net.zucks.exception.AdNetworkApiException
→ 広告配信ネットワークAPIエラー
public void onBackApplication(AdBanner adBanner) 広告タップ後アプリケーションに戻った時に通知されます。

バナー広告を画面サイズにアジャストする

バナー広告を画面の横幅(画面の短辺)に合わせて拡大する機能です。広告の表示例は以下の通りです。

バナー広告サイズアジャスト表示例(portrait)

portraitモードの広告表示例

バナー広告サイズアジャスト表示例(landscape)

landscapeモードの広告表示例

実装例

Javaコードで実装する場合にはコンストラクタ引数boolean sizeAdjusttrueを設定してください。

layout.xmlで実装する場合にはパラメータにsize_adjust="true"を設定してください。

広告を一時的に非表示にする(Javaコードでの実装時)

ポップアップ表示時など、一時的に広告を非表示にしたい場合は下記のAPIをコールしてください。

引数visibilityにはView.VISIBLE, View.INVISIBLE, View.GONEのいずれかを設定してください。

参考:Android Developers | View.setVisibility(int visibility)

ⅱ. インタースティシャル広告

アプリ終了時や、画面遷移時などに表示するインタースティシャル広告を設置します。

インタースティシャル広告の表示率は、管理画面から設定することができます。
表示率を変更したい場合、管理画面より枠の設定を変更してください。

インタースティシャル広告表示例(300x250)

インタースティシャル広告表示例

インタースティシャル広告の表示

net.zucks.view.AdInterstitialは、load()メソッドで広告情報をロードし、 その後show()メソッドを実行することでインタースティシャル広告を表示します。

広告情報のロードには通常1秒程度必要となります。
show()のタイミングより前に、余裕を持って広告情報のロードが完了するように実装してください。

複数回show()を呼び出す場合、後述の「繰り返し表示を想定した実装方法」を参考に、広告情報の再ロード処理を記述してください。

以上でインタースティシャル広告の設置が完了しました。アプリを起動し広告の表示を確認してください。

繰り返し表示を想定した実装方法

show()を行った後、再度インタースティシャル広告を表示する場合はshow()の前にload()を完了するように実装してください。
再取得を行う場合net.zucks.listener.AdInterstitialListeneronCloseAd()メソッドが最適です。
また、表示時エラーを考慮してonShowFailure(Exception e)メソッドにも実装します。

バックキー押下で広告を閉じる場合の実装方法

表示されたインタースティシャル広告をバックキーを使って閉じたい場合は
Activity内で、以下の方法で行ってください。

広告コールバック

net.zucks.listener.AdInterstitialListenerを使用して、広告情報ロード時や広告タップ時のコールバックを受け取ることが可能です。
広告情報のロードが未完了状態でshow()を実行した場合、onShowFailure(Exception e)が呼び出されます。

実装例は以下の通りです。

検知できるコールバック一覧は以下の通りです。

public void onReceiveAd() 広告情報のロード成功時に通知されます。
public void onShowAd() 広告表示時に通知されます。
public void onCancelDisplayRate() 表示率によるキャンセル時に通知されます。
public void onTapAd() 広告タップ時に通知されます。
public void onCloseAd() 広告クローズ時に通知されます。
public void onLoadFailure(Exception e) 広告情報のロード失敗時に通知されます。
エラーの内容によって以下のExceptionが設定されます。
net.zucks.exception.NetworkNotFoundException
→ オフラインエラー
net.zucks.exception.FrameIdNotFoundException
→ Frame IDエラー
net.zucks.exception.DisplaySizeTooSmallException
→ 画面サイズエラー
net.zucks.exception.AdIllegalStateException
→ 広告ステータス異常エラー net.zucks.exception.AdNetworkApiException
→ 広告配信ネットワークAPIエラー
public void onShowFailure(Exception e) 広告表示失敗時に通知されます。
エラーの内容によって以下のExceptionが設定されます。
net.zucks.exception.NetworkNotFoundException
→ オフラインエラー
net.zucks.exception.FrameIdNotFoundException
→ Frame IDエラー
net.zucks.exception.DisplaySizeTooSmallException
→ 画面サイズエラー
net.zucks.exception.AdIllegalStateException
→ 広告ステータス異常エラー net.zucks.exception.AdNetworkApiException
→ 広告配信ネットワークAPIエラー

ⅲ. 全画面(縦)インライン広告

アプリ内に全画面インライン広告を表示します。

全画面インライン広告表示例(400x600)

全画面インライン広告表示例

全画面インライン広告の表示

広告表示を行いたい任意のレイアウトファイルにnet.zucks.view.AdFullscreenBannerを追加してください。
その際、レイアウトパラメータにFrame IDを指定してください。

アプリケーション内で下記の手順でnet.zucks.view.AdFullscreenBannerのインスタンスを生成し、レイアウトに追加してください。
その際、第二引数にFrame IDを指定してください。

以上で全画面インライン広告の設置が完了しました。アプリを起動し広告の表示を確認してください。

広告コールバック

Javaコードで実装する場合、net.zucks.listener.AdFullscreenBannerListenerを使用して、広告情報のロード時や広告タップ時のコールバックを受け取ることが可能です。

実装例は以下の通りです。

検知できるコールバック一覧は以下の通りです。

public void onReceiveAd(AdFullscreenBanner banner) 広告情報のロード成功時に通知されます。
public void onTapAd(AdFullscreenBanner banner) 広告タップ時に通知されます。
public void onFailure(AdFullscreenBanner banner, Exception e) 広告情報のロード失敗時に通知されます。
エラーの内容によって以下のExceptionが設定されます。
net.zucks.exception.NetworkNotFoundException
→ オフラインエラー
net.zucks.exception.FrameIdNotFoundException
→ Frame IDエラー
net.zucks.exception.DisplaySizeTooSmallException
→ 画面サイズエラー
net.zucks.exception.ParentNotFoundException
→ 親Viewが存在していないエラー net.zucks.exception.AdIllegalStateException
→ 広告ステータス異常エラー net.zucks.exception.AdNetworkApiException
→ 広告配信ネットワークAPIエラー net.zucks.exception.AdOutOfStockException
→ 広告在庫なし

ⅳ. 全画面(縦)インタースティシャル広告

アプリ終了時や、画面遷移時などに表示する全画面インタースティシャル広告を設置します。

全画面インタースティシャル広告の表示率は、管理画面から設定することができます。
表示率を変更したい場合、管理画面より枠の設定を変更してください。

全画面インタースティシャル広告表示例(400x600)

全画面インタースティシャル広告表示例

全画面インタースティシャル広告の表示

net.zucks.view.AdFullscreenInterstitialは、load()メソッドで広告情報をロードし、 その後show()メソッドを実行することで全画面インタースティシャル広告を表示します。

広告情報のロードには通常1秒程度必要となります。
show()のタイミングより前に、余裕を持って広告情報のロードが完了するように実装してください。

以上で全画面インタースティシャル広告の設置が完了しました。アプリを起動し広告の表示を確認してください。

広告コールバック

net.zucks.listener.AdFullscreenInterstitialListenerを使用して、広告情報ロード時や広告タップ時のコールバックを受け取ることが可能です。
広告情報のロードが未完了状態でshow()を実行した場合、onShowFailure(Exception e)が呼び出されます。

実装例は以下の通りです。

検知できるコールバック一覧は以下の通りです。

public void onReceiveAd() 広告情報のロード成功時に通知されます。
public void onShowAd() 広告表示時に通知されます。
public void onCancelDisplayRate() 表示率によるキャンセル時に通知されます。
public void onTapAd() 広告タップ時に通知されます。
public void onCloseAd() 広告クローズ時に通知されます。
public void onLoadFailure(Exception e) 広告情報のロード失敗時に通知されます。
エラーの内容によって以下のExceptionが設定されます。
net.zucks.exception.NetworkNotFoundException
→ オフラインエラー
net.zucks.exception.FrameIdNotFoundException
→ Frame IDエラー
net.zucks.exception.DisplaySizeTooSmallException
→ 画面サイズエラー
net.zucks.exception.AdIllegalStateException
→ 広告ステータス異常エラー net.zucks.exception.AdNetworkApiException
→ 広告配信ネットワークAPIエラー net.zucks.exception.AdOutOfStockException
→ 広告在庫なし
public void onShowFailure(Exception e) 広告表示失敗時に通知されます。
エラーの内容によって以下のExceptionが設定されます。
net.zucks.exception.NetworkNotFoundException
→ オフラインエラー
net.zucks.exception.FrameIdNotFoundException
→ Frame IDエラー
net.zucks.exception.DisplaySizeTooSmallException
→ 画面サイズエラー
net.zucks.exception.AdIllegalStateException
→ 広告ステータス異常エラー net.zucks.exception.AdNetworkApiException
→ 広告配信ネットワークAPIエラー net.zucks.exception.AdOutOfStockException
→ 広告在庫なし

ⅴ. ネイティブ広告

アプリ内にネイティブ広告を設置します。

広告画像やテキストを自由にレイアウトし、コンテンツに馴染んだ広告表示が可能です。

ネイティブ広告表示例

ネイティブ広告表示例

基本的な表示方法

net.zucks.nativead.NativeAdClientは、load()メソッドで広告情報をロードし、 ロード完了コールバックにてNativeAdオブジェクトを取得、 広告画像やテキストをアプリ上の任意場所に設置しネイティブ広告を表示します。

ネイティブ広告を設置する箇所に以下のコードサンプルを参考に実装を行ってください。

以上で実装は完了です。
アプリをビルドして広告が表示されることを確認してください。

検知できるコールバック一覧は以下の通りです。

public void onLoadAd(NativeAd nativeAd) 広告情報のロード成功時に通知されます。
public void onNotExistAd() 広告情報が存在しない場合に通知されます。
public void onFailure(Exception e) 広告情報のロード失敗時に通知されます。
エラーの内容によって以下のExceptionが設定されます。
net.zucks.exception.NetworkNotFoundException
→ オフラインエラー
net.zucks.exception.FrameIdNotFoundException
→ Frame IDエラー
net.zucks.exception.AdNetworkApiException
→ 広告配信ネットワークAPIエラー
java.lang.IllegalStateException
→ NativeAdClientオブジェクトのステータスに異常がある場合

禁止事項

  • PR/AD表記を行なっていない
  • 誤タップを誘発させるタップ領域を設定している(広告表示領域外のタップ領域設定)
  • アイコン/ウォール広告に酷似した広告表示をしている

ⅵ. リワード広告

リワード広告を表示します。
表示形式は全画面の動画広告やインタラクティブ広告です。
広告を視聴完了したユーザに対し、アプリ内で利用可能な報酬を付与してください。

リワード広告表示例

リワード広告表示例

リワード広告枠は、現在管理画面から作成することができません。
実装をご希望のメディアパートナー様は、以下の「リワード広告を実装するメディアの登録」、「リワード広告枠作成の依頼」をお願いいたします。

リワード広告を実装するメディアの登録
管理画面にて、以下の点にご注意の上「アプリ 新規登録」をお願いいたします。

  • 「OS」はAndroidで登録お願いいたします。
  • 「マーケットURL」はリワード広告枠で必須の情報となりますので、記載をお願いいたします。
  • 広告枠の登録が必須となりますため、リワード広告枠のみご希望の場合でも仮の枠をご登録いただけますようお願いいたします。
    ※「枠編集」より枠の削除が可能となりますので、リワード広告枠作成完了後に削除お願いいたします。
  • すでに登録済みのメディアで実装をご希望の場合は、「マーケットURL」記載の確認のみお願いいたします。
    ※「アプリ説明ページ」への記載ではないことにご注意ください。

リワード広告枠作成の依頼
上記対応が完了しましたら、以下の内容で管理画面の「お問い合わせ」よりメールにてご連絡いただけますようお願いいたします。

  • 件名: リワード広告枠作成依頼
  • 本文(※以下項目をご記入ください)
  • リワード広告枠を実装したいアプリメディア名
  • アプリメディアのOS
  • 広告枠名

サンプル実装

net.zucks.sdk.rewardedad.ZucksRewardedAdを利用します。
ZucksRewardedAd#loadメソッドで広告を読み込み、ZucksRewardedAd#isAvailableメソッドでステータスを確認し、ZucksRewardedAd#showメソッドでリワード広告を表示します。
視聴完了通知をZucksRewardedAd$Listener#onShouldRewardで受け取り、ユーザに報酬を付与してください。

広告読込が未完了の状態で表示を試みた場合、ZucksRewardedAd$Listener#onPlaybackFailedが通知されます。

ZucksRewardedAdは使い捨てオブジェクトです。リワード広告の表示やエラーが発生したオブジェクトは、広告の再表示や他広告のリクエストには使用できません。
他のリワード広告をリクエストする場合、新しいZucksRewardedAdインスタンスの生成を行ってください。

下記コードサンプルを参考に、リワード広告を設置する箇所で実装してください。

広告仕様

メソッド

ZucksRewardedAdインスタンスの各メソッドを用い、広告の読込、表示、状態の確認が可能です。

#isAvailable 広告が表示可能な場合true、読込が完了していない等の事由により表示不可の場合falseを返却します。
#load 広告を読み込みます。
第1引数には現在ユーザに表示されている下記いずれかのインスタンスを設定してください。
  • android.app.Activity
  • android.app.Fragment
  • android.support.v4.app.Fragment
#show 読込済の広告を表示します。
第1引数には現在ユーザに表示されている下記いずれかのインスタンスを設定してください。
  • android.app.Activity
  • android.app.Fragment
  • android.support.v4.app.Fragment

広告イベント

ZucksRewardedAd$Listenerを実装し、イベント通知を受け取ることが可能です。

#onLoaded 広告読込完了時に通知されます。
#onLoadFailed 広告読込失敗時に通知されます。
第2引数の例外を元に適切な処理を行ってください。
#onPlaybackFailed 広告表示および再生失敗時に通知されます。
第2引数の例外を元に適切な処理を行ってください。
#onOpened 広告表示時に通知されます。
#onStarted 広告再生開始時に通知されます。
#onClicked 広告タップ時に通知されます。
#onClosed 広告表示終了時に通知されます。
#onShouldReward ユーザが報酬を受取るべき場合に通知されます。
このイベントが通知された場合、アプリ内で利用可能な報酬を付与してください。

注意: エラー発生時のコールバック内から新しい広告の読み込みを試行することは避けてください。必要な場合、読み込みの試行回数に上限を設ける等適切な制限を設定してください。
ネットワーク接続が制限された環境である場合や弊社広告在庫が不足している場合に、広告リクエストが連続して失敗することを防ぐためです。

エラー種別

ZucksRewardedAd$Listenerのコールバックで通知される例外はnet.zucks.sdk.rewardedad.ZucksRewardedAdExceptionを継承します。

エラーコード エラー種別 概要
-1 $Unknown 未知のエラー
-1000 $Timedout 広告リクエストのタイムアウト
-1001 $Offline インターネットに接続されていない
-1002 $LoadFailed 広告の読込失敗
-1003 $NoAds 広告在庫なし
-1004 $NotAvailable 広告の読込完了前のインスタンスに対する操作
-1005 $PlayFailed 広告の再生失敗
-1006 $Expired 有効期限切れ広告に対する操作
-1007 $AlreadyUsed 使用済、または使用不可になったインスタンスに対する操作
-1008 $Other 不正なFrameID、停止中の枠、その他のエラー

4. 広告が表示されない場合

導入手順に従って実装されているにも関わらず広告が表示されない等の問題が発生した場合は以下をご確認ください。

SDK導入に関するFAQ

5. 取得情報

SDKで取得している情報

Android版Zucks Ad Network SDKでは下記情報を取得し、アプリ利用者に適切な広告を表示する目的で使用しています。

  • 広告識別子(Advertising ID)
  • 行動ターゲティング広告の可否の設定状態に関する情報
  • 端末種別/端末言語設定
  • User-Agent
  • IPアドレス
  • Mobile Country Code(MCC)
  • Mobile Network Code(MNC)
  • ネットワーク種別
  • SDKのバージョン
  • アプリケーションのバージョン

オプトアウト方法など詳細に関しては、下記ページをご確認ください。