クイックスタートガイド
このクイックスタートガイドでは、Amazonモバイル広告をアプリに組み込む手順を説明します。Amazonモバイル広告APIは、現時点では、静的画像バナー、ビデオを含むエクスパンド型リッチメディアバナー、インタースティシャル広告をサポートしています。
- Amazonモバイル広告APIを使用する前に
- Google Play Services SDKをアプリに追加
- Androidアプリで広告を有効化
- 1. プロジェクトへのAPIの組み込み
- 2. Androidのマニフェストを更新
- 3. アプリキーを設定
- 4.Amazonの広告をアプリに追加
- オプション - 広告リクエストのタイムアウト値を設定
- 次のステップ
Amazonモバイル広告APIを使用する前に
Android向けのAmazonモバイル広告APIでは、Android 2.3（Gingerbread）以降が必要です。また、Android StudioまたはEclipse、Android Development Tools（ADT）プラグインをインストールしていることを前提としています。Androidの開発方法についての知識も必須です。
アカウント登録
Amazon Developer Servicesのページから、Amazonアプリとゲーム開発者ポータルのアカウントにログインします。アカウントがない場合は、アカウントを作成するように求められます。
支払い情報と税に関する情報を提出
支払い情報のページで支払い情報を提出し、税に関するインタビューのページで税に関する情報を提出します（この情報を既にAmazonアプリとゲーム開発者ポータルで提出している場合は、この手順を省略します）。この情報は、広告を受け取るために必須です。
アプリキーを取得
既存のアプリのアプリキーを取得するには、次の手順に従います。
- 開発者ポータルアカウントにログインし、[アプリ＆サービス]タブをクリックします。
- アプリをクリックします。
- [アプリサービス]（アプリタイトル下の右端のオプション）をクリックします。
- [モバイル広告]（最後のオプション）まで下にスクロールします。
- [モバイル広告を見る] をクリックします。
- アプリが13歳未満の子どもを主な対象としないことを指定します。
13歳未満の子ども向けアプリには、Amazonモバイル広告ネットワークに参加する資格がないことに注意してください。詳細については、子ども向けアプリでの広告表示を参照してください。
アプリが13才歳未満の子ども向けではないと回答した場合は、コンソールに一意のアプリキー値が表示されます。これは、アプリを識別するために使用される、全世界で一意の32文字の英数字文字列です。同じアプリキーを複数のプラットフォームで使用することができますが、アプリごとに一意のアプリキーが必要です。たとえば、IMDbアプリは、AndroidスマートフォンとFireタブレットで同じアプリキーを使用しますが、IMDb Triviaアプリは、異なるアプリキーを使用します。
アプリキーは、setAppKeyの呼び出しで使用されます（クイックスタートガイドの手順3で説明）。また、開発者レポートでは、データがアプリキー別に集計されます。アプリキーを適切に使用することで、広告料金の追跡、レポート、支払いが正確に行われます。
Google Play Services SDKをアプリに追加
2014年8月1日以降、広告を掲載するアプリをGoogle Playで配信する場合は、Googleのポリシーのページに記載されたGoogle Playサービス広告IDの条件に従う必要があります。Amazonモバイル広告APIを組み込んだアプリをGoogle Playで配信する開発者は、これらの新しい条件に従うために、次の手順を実行する必要があります。
- Google Play Services SDKのセットアップの指示に従って、アプリにGoogle Play Services SDKを組み込みます。
- 使用するAmazonのAndroid向けモバイル広告APIのバージョンが5.4.46以上であることを確認します。それよりも古いバージョンでは、必要なIDの変更がサポートされていません。
Androidアプリで広告を有効化
このセクションでは、Android StudioまたはEclipseのAndroidアプリのプロジェクトに広告を追加する手順について説明します。
1.プロジェクトへのAPIの組み込み
Amazonモバイル広告APIをAndroid Studioプロジェクトに追加する
Amazonモバイル広告APIを組み込むには、build.gradleファイルを変更する必要があります。Android Studioで次の手順を実行します。
- アプリレベルでbuild.gradleをクリックします。
-
以下のコード行を依存関係（dependencies）セクションに追加します。
compile 'com.amazon.android:mobile-ads:5.+'
図1： Android Studio環境でプロジェクトにAmazonモバイル広告APIのjarファイルを追加する画面のスクリーンショット
Amazonモバイル広告APIをEclipseプロジェクトに追加する
amazon-ads-x.y.z.jarをプロジェクトのビルドパスに追加する必要があります。Eclipseで次の手順を実行します。
- プロジェクトの [Properties] をクリックして [Properties] ダイアログボックスを表示します。
- [Java Build Path] を選択します。
- 上部の [Libraries] を選択します。
- [Add External JARs…] をクリックして [JAR Selection] ダイアログボックスを表示します。
-
[amazon-ads-x.y.z.jar] を選択し、[Open] をクリックします。
図2： Eclipse環境でプロジェクトにAmazonモバイル広告APIのjarファイルを追加する画面のスクリーンショット
2.Androidのマニフェストを更新
Amazon広告アクティビティ
Amazonモバイル広告APIでは、アプリのAndroidManifest.xmlファイルでcom.amazon.device.ads.AdActivityを宣言する必要があります。AndroidManifest.xmlファイルの<application>タグ内に、以下のAdActivity宣言を追加してください。
<activity android:name="com.amazon.device.ads.AdActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>
パーミッション
Amazonモバイル広告ネットワークに広告をリクエストするには、INTERNETパーミッションが必要です。また、ACCESS_NETWORK_STATEとACCESS_WIFI_STATEのパーミッションを含めることも強くお勧めします。これらのパーミッションを追加することで、Amazonはユーザーに対して関連性の高い、ターゲットを絞った広告を提供できるようになり、CPMの向上につながります。これらのパーミッションと追加するすべてのパーミッションは、AndroidManifest.xmlファイルの<application>タグの外部で宣言する必要があります。以下のパーミッション宣言を参照してください。
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
ACCESS_COARSE_LOCATIONパーミッションやACCESS_FINE_LOCATIONパーミッションを含めると、位置に基づくターゲティングを行うこともできます。これらのパーミッションのいずれかを含めることで、関連性の高い広告を表示できるようになり、より高いCPMを獲得する可能性があります。これらのパーミッションのいずれかが含まれている場合は、同じように宣言する必要があります。
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
enableGeoLocation APIを通じてジオ（地理的位置）ターゲティングも有効にする必要があります。マニフェストの例
AndroidManifest.xmlファイルでの宣言の実装方法の例を以下に示します。
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.company"
android:versionCode="1"
android:versionName="1.0" >
<uses-sdk android:minSdkVersion="4" android:targetSdkVersion="17" />
<application
android:icon="@drawable/ic_launcher"
android:label="@string/app_name" >
<activity
android:name=".AdTestAppActivity"
android:label="@string/app_name" >
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<activity
android:name="com.amazon.device.ads.AdActivity"
android:configChanges="keyboardHidden|orientation|screenSize"/>
</application>
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
</manifest>
3.アプリキーを設定
広告を受け取るには、アプリキーを設定する必要があります。アプリキーを設定することで、Amazonはインプレッション数やクリック数を追跡し、アカウントに関連付けることができるようになります。Amazonアプリストアから取得したアプリキーを使用して、アプリの起動時にアプリからAdRegistration.setAppKey()メソッドを呼び出します。この呼び出しは、アクティビティのonCreateメソッド、またはその他のアプリ初期化コードに追加できます。onCreateでのsetAppKeyの例を示します。
public void onCreate(Bundle savedInstanceState)
{
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
AdRegistration.setAppKey("0123456789ABCDEF0123456789ABCDEF");
}
4.Amazonの広告をアプリに追加
Amazonモバイル広告APIでは、バナー広告とインタースティシャル広告の両方がサポートされています。バナー広告（静的クリックスルー広告やエクスパンド型リッチメディア広告を含む）を作成するには、AdLayoutオブジェクトを使用します。一方、全画面広告であるインタースティシャル広告は、InterstitialAdオブジェクトを使用して作成します。AdLayoutとInterstitialAdは、両方ともAdインターフェイスを実装するJavaクラスです。
さまざまな広告の種類については、Android向けモバイル広告のコンセプトを参照してください。
Javaのコードでバナー広告を追加する
バナー広告を取得して表示するには、AdLayoutのインスタンスを使用します。このインスタンスは、コードまたはXMLで作成できます。広告を読み込むには、AdLayout.loadAdメソッドを呼び出します。このメソッドは、バックグラウンドスレッドを使用して、Amazonモバイル広告ネットワークに広告をリクエストします。
1つのAdLayoutで一度に読み込みまたは表示が可能なのは、1つの広告のみです。別の広告リクエストが保留中になっているために新しい広告のリクエストが無視された場合、AdLayout.loadAdはfalseを返します。デフォルトの動作では、広告が読み込まれた後に画面に表示されます。これは、AdLayout.autoshowプロパティがデフォルトでtrueに設定されているためです。この設定は、AdLayout.disableAutoShowメソッドまたはAdLayout.enableAutoShowメソッドを呼び出して切り替えることができます。AdLayout.disableAutoShowメソッドの呼び出しによりAdLayout.autoshowプロパティがfalseに設定されている場合は、AdLayout.showAdを呼び出して広告を表示することができます。
特定の広告が読み込み中であるかどうかを確認するには、AdLayout.isLoadingメソッドを呼び出します。特定の広告が現在表示中であるかどうかを確認するには、AdLayout.isShowingメソッドを呼び出します。広告をリクエストするときに、いくつかのターゲットパラメーターをオプションで設定することもできます。これらのパラメーターについては、広告ターゲットオプションのページで説明しています。アクティビティのonCreateメソッドに簡単なAdLayout.loadAd呼び出しを追加した例を以下に示します。
@Override
public void onCreate(Bundle savedInstanceState)
{
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
AdRegistration.setAppKey("0123456789ABCDEF0123456789ABCDEF");
// AmazonAdLayoutをプログラムで作成します
this.adView = new AdLayout(this);
LinearLayout layout = (LinearLayout) findViewById(R.id.mainLayout);
// 広告の幅と高さを正しく設定します
LinearLayout.LayoutParams lp = new LinearLayout.LayoutParams(
LinearLayout.LayoutParams.MATCH_PARENT,
LinearLayout.LayoutParams.MATCH_PARENT);
layout.addView(this.adView,lp);
// xmlでAdLayoutを宣言している場合は、代わりに
// 上記の3行を次の行に置き換えます
// this.adView = (AdLayout) findViewById(R.id.adview);
AdTargetingOptions adOptions = new AdTargetingOptions();
// オプション： ここで広告ターゲットオプションを設定します。
this.adView.loadAd(adOptions); // バックグラウンドスレッドで広告を取得します
}
アクティビティのonDestroyメソッドを以下に示します。
@Override
public void onDestroy()
{
super.onDestroy();
this.adView.destroy();
}
XMLレイアウトファイルでバナー広告を追加する
AdLayoutをXMLレイアウトファイルに追加することもできます。最初に、Amazon名前空間をルートのLayoutに、AdLayoutをlayout.xmlファイルに追加する必要があります。次のAdLayout定義の例では、Amazon:adSize属性が省略されており、広告の自動サイズ設定を使用して広告のサイズが決定されます。サイズを手動で設定する場合は、広告の手動サイズ設定セクションの説明に従って、この属性を含める必要があります。
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:Amazon="http://schemas.android.com/apk/lib/com.amazon.device.ads"
android:orientation="vertical"
android:layout_width="match_parent"
android:layout_height="match_parent">
<com.amazon.device.ads.AdLayout
android:id="@+id/adview"
android:layout_width="match_parent"
android:layout_height="wrap_content"/>
</LinearLayout>
Amazonモバイル広告APIのサンプルディレクトリには、シンプルな広告のサンプル（Simple Ad Sample）のすべてのソースファイルとプロジェクトファイルが含まれています。このサンプルは、上記で説明したものと似た実装の例を示しています。
Javaのコードでインタースティシャル広告を追加する
インタースティシャルは、アプリのバックグラウンドで読み込まれ、アプリの自然な画面遷移のタイミングでユーザーに表示される全画面広告です。インタースティシャル広告を受け取って表示するには、InterstitialAdのインスタンスをコードで作成する必要があります。広告を読み込むには、InterstitialAd.loadAdメソッドを呼び出します。このメソッドは、バックグラウンドスレッドを使用して、Amazonモバイル広告ネットワークに広告をリクエストします。
1つのInterstitialAdオブジェクトで一度に読み込むことができるのは、1つの広告のみです。また、アプリで一度に表示できるのは、1つのインタースティシャル広告のみです。別の広告リクエストが保留中になっているために新しい広告のリクエストが無視された場合、InterstitialAd.loadAdはfalseを返します。特定の広告が読み込み中であるかどうかを確認するには、InterstitialAd.isLoadingメソッドを呼び出します。
特定の広告が現在表示中であるかどうかを確認するには、InterstitialAd.isShowingメソッドを呼び出します。インタースティシャル広告が現在表示中であるかどうかを確認するには、InterstitialAd.isAdShowing静的メソッドを呼び出します。バナー広告をリクエストする場合と同様に、インタースティシャル広告をリクエストする場合にも複数のターゲットパラメーターをオプションで設定できます。これらのパラメーターについては、広告のターゲットオプションのページで説明します。
ゲームアプリの次のレベルを読み込むアクティビティのonCreateメソッドに簡単なInterstitialAd.loadAd呼び出しを追加した例を以下に示します。インタースティシャル広告は、準備が整うとすぐに表示されます。次のレベルは、ユーザーがXボタン、またはデバイスの戻るボタンを押して広告を非表示にした後に開始されます。
public class LoadNextLevel extends Activity
{
private InterstitialAd interstitialAd;
@Override
public void onCreate(Bundle savedInstanceState)
{
super.onCreate(savedInstanceState);
AdRegistration.setAppKey("0123456789ABCDEF0123456789ABCDEF");
// インタースティシャル広告を作成します。
this.interstitialAd = new InterstitialAd(this);
// リスナーを設定して以下のコールバックを使用します。
this.interstitialAd.setListener(new MyCustomAdListener());
// インタースティシャル広告を読み込みます。
this.interstitialAd.loadAd();
}
class MyCustomAdListener extends DefaultAdListener
{
@Override
public void onAdLoaded(Ad ad, AdProperties adProperties)
{
if (ad == LoadNextLevel.this.interstitialAd)
{
// アプリのユーザーにインタースティシャル広告を表示します。
// 注： この実装により、広告は読み込み終了後に直ちに表示されますが、
// ユーザーエクスペリエンスを高めるには、通常、
// 表示するタイミングより前に広告の読み込みが
// 完了するようにします。したがって、代わりに、広告が表示可能な状態であることを示す
// フラグをここに設定した後、
// 広告を表示する最適なタイミングになったら、showAd()を呼び出します。
LoadNextLevel.this.interstitialAd.showAd();
}
}
@Override
public void onAdFailedToLoad(Ad ad, AdError error)
{
// バックアップ広告ネットワークを呼び出します。
}
@Override
public void onAdDismissed(Ad ad)
{
// インタースティシャル広告が画面から消えたら、レベルを開始します。
startNextLevel();
}
}
}
Javaのコードでモードレスインタースティシャル広告を追加する
モードレスインタースティシャル広告を取得して表示するには、ModelessInterstitialAdのインスタンスを使用します。モードレスインタースティシャル広告を読み込むには、ModelessInterstitialAd.loadAdメソッドを呼び出します。このメソッドは、バックグラウンドスレッドを使用して、Amazonモバイル広告ネットワークにモードレスインタースティシャル広告をリクエストします。
1つのModelessInterstitialAdインスタンスに一度に読み込むことができるのは、1つのモードレスインタースティシャル広告のみです。別の広告リクエストが保留中になっているために、新しい広告のリクエストが無視された場合、ModelessInterstitialAd.loadAdはfalseを返します。モードレスインタースティシャル広告を読み込むときに、複数のターゲットパラメーターをオプションで設定することもできます。これらのパラメーターについては、広告ターゲットオプションのページで説明しています。
特定の広告が読み込み中であるかどうかを確認するには、ModelessInterstitialAd.isLoadingメソッドを呼び出します。読み込みが終了すると、onAdLoadedコールバックが実行され、広告を表示できるようになります。ModelessInterstitialAdには、モードレスインタースティシャル広告の準備ができているかどうかを確認する場合に便利なisReadyプロパティも用意されています。モードレスインタースティシャル広告が画面に表示されたら、インプレッション数をカウントするためにModelessInterstitialAd.adShownを呼び出す必要があります。また、モードレスインタースティシャル広告が画面から消去されたときは、ModelessInterstitialAd.adHiddenを呼び出してSDKに通知する必要があります。
以下に示すのは、複数の画像が散在する広告を表示する、SwipeableModelessInterstitialAdSampleコードの抜粋です。このサンプルでは、FragmentPagerAdapterを使用して、ユーザーの操作と表示のためのModelessInterstitialAdの作成と読み込みのプロセスを処理します。また、OnPageChangeListenerを使用して画面上のフラグメントを識別します。これにより、ユーザーに対して広告を表示するときや、非表示にするときに、ModelessInterstitialAd.adShownとModelessInterstitialAd.adHiddenを実行できるようになります。
private class ModelessInterstitialFragmentPagerAdapter extends FragmentPagerAdapter
{
private final int[] images; // 画像ギャラリーに表示するための画像一式
private int nextImageIndex; // 画像一式から表示される次の画像
private static final int PAGE_COUNT = 20;
private FrameLayout adContainerLayout;
public ModelessInterstitialFragmentPagerAdapter(FragmentManager fm)
{
super(fm);
this.images = new int[]{R.drawable.image1, R.drawable.image2, R.drawable.image3,
R.drawable.image4, R.drawable.image5};
}
@Override
public Fragment getItem(int index)
{
if (index % AD_FREQUENCY == 2)
{
this.adContainerLayout = new FrameLayout(SwipeableModelessInterstitialAdActivity.this;
modeless = new ModelessInterstitialAd(this.adContainerLayout);
modeless.setListener(new SampleAdListener());
modeless.loadAd();
// 注： 追加のターゲット情報を提供して、
// 広告のユーザーターゲティングの方法を変更することもできます。これは、
// AdTargetingOptionsパラメーターをloadAd呼び出しに渡すことで実行できます。
// 以下に例を示します。
//
// final AdTargetingOptions adOptions = new AdTargetingOptions();
// adOptions.enableGeoLocation(true);
// if (this.modelessInterstitialAd.loadAd(adOptions)) ...
}
if (index != 0 && index % AD_FREQUENCY == 0 && isReadyToShow)
{
modelessAds.put(index, modeless);
return new ModelessInterstitialFragment().setAdContainerLayout(this.adContainerLayout);
}
final ImageGalleryFragment fragment = new ImageGalleryFragment();
fragment.setImageResource(this.images[this.nextImageIndex++;
if (this.nextImageIndex == this.images.length)
{
this.nextImageIndex = 0;
}
return fragment;
}
@Override
public class int getCount()
{
return PAGE_COUNT;
}
/**
* 広告のライフサイクルイベントを追跡するイベントリスナー用のクラスです。これによって
* DefaultAdListenerを拡張することで必要なメソッドだけを上書きできるように
* なります。この場合、展開可能な広告に固有のメソッドを上書きする必要は
* ありません。
*/
private class SampleAdListener extends DefaultAdListener
{
/**
* このイベントは広告の読み込みが成功したときに1回だけ呼び出されます。
*/
@Override
public void onAdLoaded(final Ad ad, AdProperties adProperties)
{
Log.i(LOG_TAG, adProperties.getAdType().toString() + "広告が正常に読み込まれました。");
isReadyToShow = true;
}
/**
* このイベントは広告の読み込みに失敗したときに呼び出されます。
*/
@Override
public void onAdFailedToLoad(final Ad view, final AdError error)
{
Log.w(LOG_TAG, "広告を読み込めませんでした。Code: " + error + ", Message: " + error.getMessage());
isReadyToShow = false;
}
}
}
/**
* ページ変更イベントをキャプチャするために使用します
*/
private class ModelessInterstitialOnPageChangeListener implements OnPageChangeListener
{
private int prevPosition = -1; // 前の画面上フラグメントのインデックス
private int currPosition = -1; // 現在の画面上フラグメントのインデックス
@Override
public void onPageScrollStateChanged(final int state)
{
switch(state)
{
case ViewPager.SCROLL_STATE_IDLE:
ModlessInterstitialAd modelessAd = modelessAds.get(this.currPosition);
if (modelessAd != null)
{
modelessAd.adShown();
}
modelessAd = modelessAds.get(this.prevPosition);
if (modelessAd != null)
{
modelessAd.adHidden();
}
break;
default:
break;
}
}
@Override
public void onPageScrolled(final int position, final float positionOffset, final int positionOffsetPixels)
{}
@Override
public void onPageSelected(final int position)
{
this.prevPosition = this.currPosition;
this.currPosition = position;
}
}
オプション - 広告リクエストのタイムアウト値を設定
広告リクエスト呼び出しのデフォルトのタイムアウトは10秒です。タイムアウトのしきい値を超えた後は、AdListener.onAdFailedToLoadイベントが呼び出されます。デフォルトのタイムアウト値は、AdLayout.setTimeoutメソッドを使用して変更できます。このメソッドは、引数としてミリ秒単位の時間を受け取ります。
例：
AdLayout adLayout = new AdLayout();
adLayout.setTimeout(20000); // 20秒
次のステップ
次のセクションに目を通してください。
/Ads/samplesディレクトリにあるサンプルアプリを1つ以上コンパイルしてお試しください。シンプルな広告のサンプルは、広告を読み込む基本的な方法を示しています。フローティング広告のサンプルは、画面の下部から浮き上がる広告の読み込み方法を示しています。インタースティシャル広告のサンプルは、インタースティシャル広告を読み込んで表示する方法を示しています。スワイプ可能なモードレスインタースティシャル広告のサンプルは、スワイプジェスチャーによる遷移でモードレスインタースティシャル広告を読み込んで表示する方法を示しています。また、枠付きモードレスインタースティシャル広告のサンプルは、枠付きのコンテキストでモードレスインタースティシャル広告を読み込み表示する方法を示しています。