クイックスタートガイド


クイックスタートガイド

このクイックスタートガイドでは、Amazonモバイル広告をアプリに組み込む手順を説明します。Amazonモバイル広告APIは、現時点では、静的画像バナー、ビデオを含むエクスパンド型リッチメディアバナー、およびインタースティシャル広告をサポートしています。

Amazonモバイル広告APIを使用する前に

AmazonのAndroid向けモバイル広告APIでは、Android 2.3(Gingerbread)以降が必要です。また、Android StudioまたはEclipse、およびAndroid Development Tools(ADT)プラグインをインストールしていることを前提としています。Androidの開発方法についての知識も必要となります。

アカウント登録

Amazon Developer Servicesのページから、Amazonアプリおよびゲーム開発者ポータルのアカウントにサインインします。アカウントを持っていない場合は、アカウントを作成するように求められます。

支払い情報および税に関する情報を提出する

支払い情報のページで支払い情報を提出し、税に関するインタビューのページで税に関する情報を提出します(この情報を既にAmazonアプリおよびゲーム開発者ポータルで提出している場合は、この手順をスキップします)。この情報は、広告を受け取るために必要となります。

アプリキーを取得する

サインインしたら、[マイアプリ] タブをクリックし、既存のアプリを選択するか、[新規アプリを追加] ボタンをクリックします。新しいアプリを作成する場合は、[アプリタイトル] フィールドと [カテゴリー] フィールドに入力し、[保存] ボタンをクリックします。[モバイル広告] タブをクリックし、子供向けの質問に回答し、[申請] をクリックします。13歳未満の子供向けアプリには、Amazonモバイル広告ネットワークに参加する資格がないことに注意してください。詳細については、FAQにある個人情報とCOPPAを参照してください。

アプリが13才歳未満の子供向けではないと回答した場合は、</span>次の画面に一意のアプリキー値が表示されます。これは、アプリを識別するために使用される、全世界で一意の32文字の英数字文字列です。同じアプリキーを複数のプラットフォームで使用することができますが、個別の各アプリが一意のアプリキーを持っている必要があります。たとえば、IMDbアプリは、AndroidスマートフォンとFireタブレットで同じアプリキーを使用しますが、IMDb Triviaアプリは、異なるアプリキーを使用します。

アプリキーは、setAppKeyの呼び出しで使用されます(クイックスタートガイドの手順3で説明)。また、開発者レポートでは、データがアプリキー別に集計されます。アプリキーを適切に使用することで、広告料金の追跡、レポート、および支払いが正確に行われます。

注: あるアプリに対して発行されたアプリキーを、別のアプリで広告を掲載するために使用した場合は、別のアプリに掲載された広告のインプレッション、クリック、その他のユーザー操作については支払いが行われませんのでご注意ください。

Google Play Services SDKをアプリに追加する

重要: 2014年8月1日以降にアプリをGoogle Playストアに申請する予定の場合は、この手順を必ず行ってください。それ以外の場合は、このセクションをスキップしても構いません。

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を組み込む
  2. Androidのマニフェストを更新する
  3. アプリキーを設定する
  4. Amazonの広告をアプリに追加する

注: Amazonモバイル広告APIをAmazon Mobile App SDK Eclipseプラグインからプロジェクトに組み込む場合、手順1および手順2は自動的に実行されます。Eclipseプラグインの詳細については、Eclipseプラグインのページを参照してください。

1. プロジェクトにAPIを組み込む

Amazonモバイル広告APIをAndroid Studioプロジェクトに追加する

Amazonモバイル広告APIを含めるには、build.gradleファイルを変更する必要があります。Android Studioで次の手順を実行します。

  1. アプリレベルでbuild.gradleをクリックします。
  2. 以下のコード行を依存関係セクションに追加します。

compile 'com.amazon.android:mobile-ads:5.+'

図1: Android Studio環境でプロジェクトにAmazonモバイル広告APIのjarファイルを追加する画面のスクリーンショット

Amazonモバイル広告APIをEclipseプロジェクトに追加する

amazon-ads-x.y.z.jarをプロジェクトのビルドパスに追加する必要があります。Eclipseで次の手順を実行します。

  1. プロジェクトの [Properties] をクリックして [Properties] ダイアログボックスを表示します。
  2. [Java Build Path] を選択します。
  3. 上にある [Libraries] を選択します。
  4. [Add External JARs...] をクリックして [JAR Selection] ダイアログボックスを表示します。
  5. [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ファイルのアプリタグ内に、以下の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ファイルのアプリタグの外部で宣言する必要があります。以下の権限の宣言を参照してください。

```


ACCESS_COARSE_LOCATION権限とACCESS_FINE_LOCATION権限を含めて位置に基づくターゲティングを行うこともできます。これらの権限のいずれかを含めることで、関連性の高い広告を表示できるようになり、より高いCPMを獲得する可能性があります。これらの権限のいずれかが含まれている場合は、同じ方法で宣言する必要があります。
**重要**: 位置に基づくターゲティングを行う場合は、広告のターゲティングオプションのセクションで説明するように、enableGeoLocation APIを通して地理的な位置のターゲティングも有効にする必要があります。

### マニフェストの例

以下に、AndroidManifest.xmlファイルでの宣言の実装方法の例を示します。
```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 Mobile App Distributionから取得したアプリキーを使って、アプリから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();
}

: AmazonのAndroid向けモバイル広告SDKで、レイアウトのサイズおよびデバイスの画面サイズに応じて自動的に広告のサイズを選択するには、Androidの概念の「広告の自動サイズ設定」セクションに記載されているガイドラインに従う必要があります。上記の実装では、デフォルトで広告の自動サイズ設定を使用しています。サイズを手動で設定する場合は、Androidの概念の「広告の手動サイズ設定」セクションの指示に従います。

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
    {
        /**
         * このイベントは広告の読み込みが成功したときに一度だけ呼び出されます。
         */
        @Override
        public void onAdLoaded(final Ad ad, AdProperties adProperties)
        {
            Log.i(LOG_TAG, adProperties.getAdType().toString() + "ad loaded successfully.");
            isReadyToShow = true;
        }

        /**
         * このイベントは広告の読み込みに失敗したときに呼び出されます。
         */
        @Override
        public void onAdFailedToLoad(final Ad view, final AdError error)
        {
            Log.w(LOG_TAG, "Ad failed to load.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ディレクトリにある複数のサンプルアプリをコンパイルしてお試しください。シンプルな広告のサンプルは、広告を読み込む基本的な方法を示しています。フローティング広告のサンプルは、画面の下部から浮き上がる広告の読み込み方法を示しています。インタースティシャル広告のサンプルは、インタースティシャル広告を読み込んで表示する方法を示しています。スワイプ可能なモードレスインタースティシャル広告のサンプルは、スワイプジェスチャーによる遷移でモードレスインタースティシャル広告を読み込んで表示する方法を示しています。また、枠組みされたモードレスインタースティシャル広告のサンプルは、枠組みされたコンテキストでモードレスインタースティシャル広告を読み込んで表示する方法を示します。