必要条件

この記事に必要な予備知識

Flash BuilderまたはFlash ProfessionalとAdobe AIRでAndroid用アプリを構築した経験があると、この記事を最大限に活用できます。



必要となるほかの製品

Milkman GamesのAmazon In-App Purchase Extension for Adobe AIR

ユーザーレベル

中級

Amazon Appstoreと非常に人気のあるKindle Fireは、開発者にとって巨大な市場であり、アプリを収益化する大きなチャンスです。Milkman GamesのAmazon In-App Purchase Extension for Adobe AIRを利用すると、使い慣れた簡単なActionScript 3インターフェイスを使用して、AmazonのIn-App PurchaseシステムをAIRおよびFlashのアプリに統合できます。

Amazon In-App Purchase Extension for Android and Kindle fireは、次のことが可能になる100%ネイティブのJavaソリューションです。

  • アプリを無料で提供し、アプリ内課金で収益を得る
  • Amazonの「Free App Of The Day(本日の無料アプリ)」で紹介され、オプションアイテムの購入により収益を得る
  • わずか数行のコードで簡単に統合して購入可能にできる
  • 消費アイテム、資格アイテム、購読アイテムをサポート

「Amazon Developer(Amazonデベロッパー)」のパブリッシングアカウントでのアプリの設定

Amazonのアプリ内課金を利用する前に、Amazonの開発者Webサイトで購入可能なアイテムを定義する必要があります。

  1. http://developer.amazon.comに移動し、自分の開発者アカウント資格情報を使用してログインします。
  2. 新しいアプリケーションを作成する場合、「Home(ホーム)」画面から「Add New App(新しいアプリを追加)」をクリックします(図1参照)。既存のアプリにアプリ内課金を追加する場合には、手順4に進みます。
  1. アプリのタイトル、形態、説明および連絡先情報を入力し、「Save(保存)」をクリックします(図2参照)。
  1. 「Home(ホーム)」画面で、アプリ内課金を追加するアプリケーションの横の「Actions(アクション)」をクリックし、「In-App Items(アプリ内課金アイテム)」を選択します(図3参照)。

「In-App Items(アプリ内課金アイテム)」画面で、画面右上の「Add In-App Item(アプリ内課金アイテムを追加)」を選択します。「Add Consumable(消費アイテムを追加)」、「Add Entitlement(資格アイテムを追加)」、「Add Subscription(購読アイテムを追加)」の3つのオプションが表示されます(図4参照)。

消費アイテムは何度も購入でき、アプリ内で使い切られるか、消費される製品です。消費アイテムとは、ゲームコインのパックなどです。ユーザーはコインを買い、ゲーム内で使い、またコインを買い足すことができます。

資格アイテムは、一度購入すれば永久に所有できる製品です。資格アイテムとは、ゲームの新しいレベルのパックまたはユーティリティアプリの機能制限の解除などです。

購読アイテムは、機能またはコンテンツのセットを一定の期間有効にするために購入されます。期間が過ぎると、購読は更新できます。毎月新しい記事を配信する雑誌などが購読アイテムにあたります。

追加するアイテムの種類を選択します。以下の例では消費アイテムを使用します。

  1. 次の画面で、消費アイテムの詳細を入力します。「Title(タイトル)」フィールドおよび「Description(説明)」フィールドは、アップロードするマルチメディアコンテンツとともにエンドユーザーに表示されます。「SKU(SKU)」フィールドは、このアイテム固有の識別子です。ユーザーがこれを見ることはありませんが、後で自分のアプリからアイテムをプログラムで購入する際に必要になるので、自分が選択したSKUは必ず把握しておいてください。アイテムの設定が完了したら、「Save(保存)」を選択します(図5参照)。

さらにアプリ内課金をアプリに追加するには、必要に応じて前述の手順を繰り返します。

アイテムリストJSONファイルの作成とインストール

アプリをAppstoreに申請する前にアプリ内課金をテストするには、購入のためのすべてのメタデータが含まれるJSON形式の特別なファイルを作成する必要があります。サンドボックスモードのとき、このファイルはアプリが購入要求にどのように応答するのかを決定します。

次の例に、このファイルが取る必要のある形式を示します。ここには、例としてmy_levelpackという名前の資格アイテムのSKU my_spellを持つ消費アイテムが含まれます。SKU、タイトル、説明およびほかのデータがデベロッパーポータルで入力したものと一致するように注意してください。

ファイル名は、amazon.sdktester.jsonとします。拡張パッケージの /example フォルダーに、このファイルの参考例があります。

ファイル形式について詳しくは、https://developer.amazon.com/sdk/in-app-purchasing/documentation/testing-iap.html#Create JSONを参照してください。

  1. 次の例を参考に、ご利用のテキストエディターでamazon.sdktester.jsonというファイルを作成します。自分の購入用のSKUおよびその他の情報を使用してください。
{ “my_spell” : { “itemType”: “CONSUMABLE”, “price”: 0.99, “title”: “Consumable Spell”, “description”: “It's a spell”, “smallIconUrl”: “http://some/image.jpg” }, “my_levelpack” : { “itemType”: “ENTITLED”, “price”: 0.99, “title”: “Level Pack 1”, “description”: “More levels for this game!”, “smallIconUrl”: “http://some/image.jpg” } }
  1. ご使用のコンピューターの任意の場所にファイルを保存します。
  2. コンピューターのUSBポートにKindle FireまたはほかのAndroidデバイスを接続します。
  3. Windowsのコマンドプロンプト(スタート/実行で、cmdと入力しEnterキーを押す)またはiOSのターミナル(アプリケーション/ターミナル)を開きます。
  4. JSONファイルの場所へ移動します。Windowsでファイルが C:\dev\に保存された場合には、cd c:\devと入力しEnterキーを押します。

    iOSでファイルが /yourusername/devに保存された場合には、cd /Users/yourusername/devcdと入力しReturnキーを押します。

  5. Android SDKに付属のadbプログラムを実行します。(SDKがない場合には、http://developer.android.com/sdk/index.htmlから入手できます)。JSONファイルの場所を1つ目のパラメーターとし、/mnt/sdcardを2つめのパラメーターとして渡して、pushコマンドを実行します。

    WindowsでAndroid SDKが C:\dev\android-sdkにある場合、c:\dev\android-sdk\platform-tools\adb push amazon.sdktester.json /mnt/sdcardと入力してEnterキーを押します。

  6. iOSでAndroid SDKが /Users/yourusername/android-sdkにある場合、/Users/yourusername/android-sdk/platform-tools/adb push amazon.sdktester.json /mnt/sdcardと入力してReturnキーを押します。

Amazon SDK Testerアプリケーションのインストール

Amazon Purchasesをローカルでテストする前に、Amazon SDK Testerと呼ばれる特別なテストアプリケーションをインストールする必要があります。このアプリはAmazon SDKに含まれ、Amazon SDKはhttps://developer.amazon.com/sdk.htmlからダウンロードできます。

このアプリをインストールするには、Android SDKのadbコマンドを再度使用します。

  1. コンピューターのUSBポートにKindle FireまたはほかのAndroidデバイスを接続します。
  2. コマンドプロンプトを開きます。
  3. Amazon SDKツールの場所まで移動し、Android SDKに付属のadbプログラムを実行します。Amazon SDK TesterアプリAPKをパラメーターとして渡してinstallコマンドを実行します。
  4. WindowsでAmazon SDKが C:\dev\In-App-Purchasing に保存され、 Android SDKが C:\dev\android-sdkにある場合、次のコマンドを実行します。
cd c:\dev\In-App-Purchasing\tools c:\dev\android-sdk\platform-tools\adb install -r AmazonSDKTester.apk
  1. iOSでAmazon SDKが /yourusername/dev/In-App-Purchasing に保存され、Android SDKが /Users/yourusername/android-sdkにある場合、次のコマンドを実行します。
cd /Users/yourusername/dev/In-App-Purchasing/tools ./Users/yourusername/android-sdk/platform-tools/adb install -r AmazonSDKTester.apk

ライブラリの追加

次の手順では、com.milkmangames.nativeextensions.AmazonPurchase.aneライブラリをプロジェクトに追加します(Flash Builder 4.6以降またはFlash Professional CS6以降を使用していない場合には、代わりにAmazonPurchaseAPI.swcライブラリを追加する必要があります)。

Flash Professional CS6では次のように行います。

  1. Android用のタイプAIRの新規プロジェクトを作成します。
  2. ファイル/パブリッシュ設定を選択します。
  3. 「Script for ActionScript Settings(ActionScript設定のスクリプト)」の横のレンチアイコンをクリックします。
  4. 「ライブラリパス」タブを選択します。
  5. 「Browse For Native Extension (ANE) File(ネイティブ拡張機能(ANE)ファイルの参照)」をクリックし、com.milkmangames.nativeextensions.AmazonPurchase.aneファイルを選択します。

Flash Builder 4.6では次のように行います。

  1. プロジェクトプロパティに移動します(パッケージエクスプローラーで右クリックし、「プロパティ」を選択)。
  2. ActionScriptビルドパスを選択し、「Native Extensions(ネイティブ拡張機能)」タブをクリックします。
  3. 「Add ANE(ANEを追加)」をクリックして、com.milkmangames.nativeextensions.AmazonPurchase.aneファイルに移動します。
  4. ActionScript Build Packaging(ActionScript Buildパッケージング)/Packaging(パッケージング)/Androidを選択します。
  5. 「Native Extensions(ネイティブ拡張機能)」タブを選択し、拡張機能の横の「パッケージ」チェックボックスをクリックします。

FlashDevelopでは次のように行います。

  1. プロジェクトフォルダーにAmazonPurchaseAPI.swcファイルをコピーします。
  2. エクスプローラーパネルで、SWCを右クリックし、「Add To Library(ライブラリに追加)」を選択します。
  3. エクスプローラーパネルで再びSWCファイルを右クリックし、「Options(オプション)」を選択し、「External Library(外部ライブラリ)」を選択します。

APIの概要

Amazon In-App Purchaseの拡張機能は、数回の単純な呼び出しで作動できます。完全な例については、 example/AmazonExample.as を参照してください。

初めに、以下の手順を実行します。

  1. APIクラスをインポートします。
com.milkmangames.nativeextensions.android.*; com.milkmangames.nativeextensions.android.events.*;
  1. AmazonPurchase.create()を呼び出して、APIを初期化します。最初にAmazonPurchase.isSupported()メソッドをチェックすることで、現在のプラットフォームがAndroidであって、サポートされていないプラットフォーム(iOSまたはWindows)でないことを確認できます。
if (AmazonPurchase.isSupported()) { AmazonPurchase.create(); }
  1. create()が呼び出されると、AmazonPurchase.amazonPurchaseにアクセスすることによって、AmazonPurchase APIのインスタンスが静的に使用可能になります。考えられるすべてのAPI応答に対してイベントリスナーを追加します。
// item data listeners AmazonPurchase.amazonPurchase.addEventListener(AmazonPurchaseEvent.ITEM_DATA_LOADED,onDataLoaded); AmazonPurchase.amazonPurchase.addEventListener(AmazonPurchaseEvent.ITEM_DATA_FAILED,onDataFailed); // item purchase listeners AmazonPurchase.amazonPurchase.addEventListener(AmazonPurchaseEvent.PURCHASE_ALREADY_ENTITLED,onAlreadyEntitled); AmazonPurchase.amazonPurchase.addEventListener(AmazonPurchaseEvent.PURCHASE_FAILED,onPurchaseFailed); AmazonPurchase.amazonPurchase.addEventListener(AmazonPurchaseEvent.PURCHASE_SKU_INVALID,onInvalidSku); AmazonPurchase.amazonPurchase.addEventListener(AmazonPurchaseEvent.PURCHASE_SUCCEEDED,onPurchaseSuccess); // purchase update listeners AmazonPurchase.amazonPurchase.addEventListener(AmazonPurchaseEvent.PURCHASES_UPDATE_FAILED,onUpdateFailed); AmazonPurchase.amazonPurchase.addEventListener(AmazonPurchaseEvent.PURCHASES_UPDATED,onPurchasesUpdate);

購入更新イベントの処理

APIを初期化し、イベントハンドラーを設定すると、AmazonPurchaseEvent.PURCHASES_UPDATEDイベントをいつでも受けることができるようになります。このイベントにはパラメーターreceiptsが含まれます。これには、ユーザーが購入した非消費アイテムのAmazonPurchaseReceiptオブジェクトのアレイが含まれます。次のコード例は、これらの受け取りに対する反復操作を行う方法を示しています。

private function onPurchasesUpdate(e:AmazonPurchaseEvent):void { for each(var receipt:AmazonPurchaseReceipt in e.receipts) { trace(“you previously bought a “+receipt.sku); // update your internal state for the items here. } }

アイテムデータの取得

AmazonPurchase.amazonPurchase.loadItemData()メソッドを使用して、タイトル、説明、アイコンなどの詳細をSKUの特定のセットに関連するものとして、次のように取得できます。

AmazonPurchase.amazonPurchase.loadItemData([“my_spell”,”my_levelpack”]);

完了時に、この関数は提供されたSKUの詳細を含むAmazonPurchaseEvent.ITEM_DATA_LOADEDイベントをディスパッチします。要求に失敗すると、AmazonPurchaseEvent.ITEM_DATA_FAILEDがディスパッチされます。

次のコードは、itemDatasに対する反復操作を実行し、SKUを表示することを示しています。さらに、プロパティunavailableSkusをチェックします。これは提出したSKUのアレイで無効なものです。

private function onDataLoaded(e:AmazonPurchaseEvent):void { for each(var item:AmazonItemData in e.itemDatas) { trace("sku="+item.sku+",price="+item.price+ ",iconUrl="+item.smallIconUrl+",title="+item.title+ ",description="+item.description); } for each(var badSku:String in e.unavilableSkus) { trace("this sku was not available:"+badSku); } }

購入の実行

アプリのコードからアイテムの購入を開始するには以下の手順に従います。

  1. アイテムの購入を開始し、ユーザーにチェックアウトダイアログボックスを表示するには、purchaseItem(itemSku)メソッドを使用します。itemSkuは先に作成した製品SKUのうちの1つです。例えば、次のようになります。
AmazonPurchase.amazonPurchase.purchaseItem("your_itemsku");
  1. 購入プロセスが完了すると、表1に示されたイベントのうち1つを受け取ります。

表1.購入イベント

イベント

説明

AmazonPurchaseEvent.PURCHASE_SUCCEEDED

購入は成功しました。イベントのreceiptsパラメーターは購入アイテムのAmazonPurchaseReceiptオブジェクトを1つ含むベクトルアレイです。

AmazonPurchaseEvent.PURCHASE_FAILED

購入は、エラーまたはユーザーが購入を中止したために成功しませんでした。

AmazonPurchaseEvent.SKU_INVALID

指定されたitemSkuはシステムにありませんでした。

AmazonPurchaseEvent.PURCHASE_ALREADY_ENTITLED

ユーザーは指定された非消費アイテムを既に持っています。

アプリケーション記述ファイルの更新

AIR 3.0 SDK(またはそれ以降)を使用し、Amazon In-App Purchase拡張機能を含み、Androidのマニフェスト追加をAmazon In-App Purchaseの特定の設定に更新するように、AIRアプリケーション記述ファイルを設定する必要があります。実用的な例については、 example/app.xmlを参照してください。

  1. アプリケーション記述ファイルで、AIR SDKを3.0(または3.0以上)に設定します。
<application xmlns=“http://ns.adobe.com/air/application/3.0”>
  1. 記述に拡張機能へのリンクを含めます。
<extensions> <extensionID>com.milkmangames.extensions.AmazonPurchase</extensionID> </extensions>
  1. Androidマニフェスト追加を更新します。Amazon In-App Purchaseを機能させるには、android.permission.INTERNET許可が必要です。また、以下に示すように、<intent-filter>要素内にcom.amazon.inapp.purchasing.NOTIFYアクションを追加する必要があります。
<android> <manifestAdditions><![CDATA[ <manifest android:installLocation=“auto”> <uses-permission android:name=“android.permission.INTERNET”/> <application> <receiver android:name="com.amazon.inapp.purchasing.ResponseReceiver"> <intent-filter> <action android:name="com.amazon.inapp.purchasing.NOTIFY" android:permission="com.amazon.inapp.purchasing.Permission.NOTIFY" /> </intent-filter> </receiver> </application> </manifest> ]]></manifestAdditions> </android>

アプリの構築とトラブルシューティング

Flash Builder 4.6以降またはFlash Professional CS6以降を使用しており、前述のようなAmazon In-App Purchase拡張ライブラリを追加した場合には、普段行っているようにIDEから直接コンパイルできます。それ以外の場合で、コマンドラインから拡張機能を使用してアプリを構築する場合は、com.milkmangames.nativeextensions.AmazonPurchase.aneファイルを含むディレクトリを指定する必要があります。

以下にコマンドラインで構築する例を示します。

[PATH_TO_AIR_SDK]\bin\adt -package -target apk-debug -storetype pkcs12 -keystore [YOUR_KEYSTORE_FILE] -storepass [YOUR_PASSWORD] anesample.apk app.xml anesample.swf -extdir [DIRECTORY_CONTAINING_ANE_FILE]

アプリが期待したイベントを受け取らない場合、以下のヒントを参考にしてください。

  • 前述のように、アプリケーション記述XMLファイルに適切なmanifestAdditionsを追加していることを確認する。
  • テスターJSONファイルの形式を再確認する。エラーや文字の欠落がある場合には、Amazon Purchaseテストはサイレントに失敗します。

次のステップ

これで自身のアプリでAmazon In-App Purchasesが作動するようにできたので、その他のネイティブ拡張機能のチュートリアルに進むことができます。