fxPay を使用したアプリ内課金

草案
このページは完成していません。

fxPay は、Open Web Apps に対して、アプリ内課金の設定、アプリ内課金製品の管理、購入レシートからの製品の復元を行うための JavaScript ライブラリです。Firefox Marketplace API よって提供されるアプリ内課金サービスのラッパーであり、mozPay とどちらを使用するかを選択することができます。mozPay と異なり、fxPay はアプリ内課金製品をユーザに提供するための完全なソリューションです。暗号化された署名を検証するためにアプリが独自のサーバをホストする必要はありません。また、mozPay と比べて、作成する独自のコードが少しで済みます。この記事では、fxPay API のステータス、使用の前提条件、およびライブラリの各機能の使用方法について説明します。

ステータス

このライブラリは、アプリの決済処理のための推奨されるツールですが、まだ実験的に提供されている状態です。ぜひこのライブラリを使用し、バグの解決にご協力ください。ただし、この API を使用した場合、最終版が提供されるまで、その変更によって影響を受ける可能性があります。この API が実験段階にあることに抵抗がある場合は、mozPay を使用してください。

前提条件

fxpay を使用してアプリ内課金を処理するには、次の要件を満たす必要があります。

アプリが Firefox OS 1.1 以上で動作する必要があります。
マニフェストのレシート検証をするにはオリジンが宣言されている必要があります。
Marketplace API とやり取りするためマニフェストで次の許可が宣言されている必要があります。
```
"permissions":{
  "systemXHR":{
    "description":"Required to access payment API"
  }
}
```
アプリケーションが、権限付きのパッケージ型アプリである必要があります。これにより、署名し、適切な許可を付与することができます。

次で説明するサンプルアプリでは、これらの設定方法がすべて示されています。

サンプルアプリ

fxpay を使用した実際の例については、こちらを参照してください。サンプルアプリを Firefox OS デバイスにインストールする手順については、アプリのページの README を参照してください。このアプリを使用して、fxpay とその関連の API をテストすることもできます。

API ガイド

次のガイドでは、fxpay JavaScript ライブラリを使用して決済と製品を処理する方法について説明します。

インストール

fxpay を使用するには、Web アプリケーション内に、JavaScript ライブラリを組み込む必要があります。Bower パッケージマネージャーで、次のコマンドを使用してアプリ内にライブラリをインストールします。

bower install fxpay

これで、アプリの HTML で次のスクリプトタグを使用して、ライブラリにリンクできるようになります。

<script src="bower_components/fxpay/lib/fxpay.js" type="text/javascript"></script>

あるいは、Bower ツールを使用して管理対象スクリプトの読み込みや圧縮を行うこともできます。Bower を使用しない場合は、fxpay の Git リポジトリ経由で最新の安定したソースをダウンロードしてください。

アプリのセットアップ

Firefox Marketplace Developer Hub にログインし、次の標準プロセスに従って、アプリをアップロードします。[Compatability & Payments] ページの [Prices & Countries] の下でアプリ内課金を [Yes] に設定し、変更を保存します。次に [In-App Payments] ページを開き、[Configure In-App Products] をクリックします。[In-App Products] ページが開き、アプリ内課金製品の作成と編集が行えるようになります。このページの使用方法の詳細については、アプリ内課金製品を参照してください。

初期化

アプリの起動時に、アプリが既存の製品レシートを確認できるように、fxpay を初期化する必要があります。またこのときに、一般的なエラー処理などのイベントのコールバックを登録することもできます。

fxpay.init({
  onerror: function(error) {
    console.error('An error occurred:', error);
  },
  oninit: function() {
    console.log('fxpay initialized without errors');
  },
  onrestore: function(error, product) {
    // If error is null, product.productId has been 
    // restored from receipt.
  }
});

製品の取得

アプリのすべての製品を取得するには、初期化の後に fxpay.getProducts() を呼び出します。

fxpay.init({
  oninit: function() {

    fxpay.getProducts(function(error, products) {
      if (error) {
        return console.error('Error getting products:', error);
      }

      console.log('first product ID:', products[0].productId);
      console.log('first product name:', products[0].name);
    });
  }
});

エラーが発生しなければ、コールバックによって一連の製品情報オブジェクトが起動されます。このメソッドは、ユーザが製品の購入に使用するインターフェイスを構築するのに役立ちます。

フェイク製品の使用

先に Firefox Marketplace Developer Hub で製品を設定するのではなく、まず決済に対応するアプリを作成する場合、フェイク製品を使用することができます。これにはアプリの初期化の任意の場所に、次のように設定します。

fxpay.configure({fakeProducts: true});

これにより、fxpay.getProducts(...) が変更され、シミュレーションモードで購入できる 2 つの事前設定の製品が返されるようになります。これらの製品では、ID 文字列、名前、および価格帯が固定されていますが、このことは、購入とアプリ提供のコールバックの統合に役立ちます。

完成したアプリおよび設定が完了した製品を登録した後、fakeProducts を false に設定すると、fxpay.getProducts(...) への同じ呼び出しによって、アプリの実際の製品が取得されます。

レシートからの製品の復元

fxpay.init() は、ユーザのデバイス上にあるすべてのレシートを検出して検証します。レシートが有効な場合は、ユーザがその製品を購入済みであることを意味するため、その製品を使用できるようにする必要があります。

復元された各製品に対し、onrestore コールバックが起動されます。最初の引数は、エラー文字列です。これは null の場合もあります。2番目の引数は、製品情報オブジェクトです。これも、エラーによっては null の場合があります。

コールバックは、次のように初期化します。

fxpay.init(
  onrestore: function(error, product) {
    if (error) {
      console.error('Error', error, 'while restoring', 
                    product.productId);
    } else {
      console.log(product.productId, 'restored from receipt');
    }
  }
});

外部レシートの拒否

fxpay.init() は無効なレシートを拒否するだけでなく、外部アプリに属しているために、製品の URL がアプリの提供元に一致しないすべてのレシートを拒否します。このようなレシートは、ユーザが別のアプリから製品を購入し、それを目的のアプリの記憶領域にコピーして無料で利用しようとする場合に処理が必要になります。この検証を無効にし、あらゆる アプリに属する有効なレシートを使用可能にするには、設定を使用して allowAnyAppReceipt = true に設定します。

購入情報の取得

アイテムの購入フローを開始するには、fxpay.purchase() を呼び出します。通常はまず、fxpay.getProducts() によって得た結果に基づき、購入できる製品をアプリ内に表示する画面を作成します。.次のように、購入ボタンを作成します。このボタンは、タップすると fxpay.purchase() が呼び出されます。

var productId = 'a1bcdeffe3';  // from getProducts().

fxpay.purchase(productId, function(error, product) {
  if (error) {
    return console.error(error);
  }

  console.log(product.productId, 'purchased and verified!');
  // ***************************************************
  // It is now safe to deliver the product to your user.
  // ***************************************************
});

purchase コールバックによって、エラー文字列 (null の場合を含む) と製品情報オブジェクトが取得されます。コールバックは、ユーザが購入フローを完了し、Marketplace サーバがレシートを検証し終わって、製品をユーザに提供しても安全な状態になった時点で起動されます。

これはどのような仕組みでしょうか。fxpay.purchase() 関数は、mozPay() を呼び出し、着信 JWT の署名を受け取って検証するプロセスを自動的に実行します。詳細については、アプリ内課金ガイドを参照してください。ただし、fxpay ライブラリを使う場合には詳細を理解する必要はありません。

製品情報オブジェクト

purchase および onrestore コールバックは、製品情報オブジェクトを受信します。エラーが発生した場合、エラー状態に応じて、不足しているプロパティを持つオブジェクトを受け取ることができます。製品情報オブジェクトには、次のプロパティが含まれています。

product.productId: 製品を識別するための固有の文字列。製品を管理する際に Firefox Marketplace Developer Hub に表示される識別子に対応します。
product.name: 標準ロケールでの製品名。
product.productUrl: レシートで宣言されている製品の URL。通常はアプリの URL で、https://your-hosted-app や app://your-packaged-app という形式で表されます。
product.smallImageUrl: 64 ピクセル四方の製品の画像。

エラー

エラーは通常、コールバックへの最初の引数として返されます。エラーは文字列であって、コンソールに出力される判読可能なコードか、またはユーザにエラーを表示するためのローカライズしたテキストへのマップと同様に処理する必要があります。エラーの詳細な説明は自動的にログに記録されます。詳細については、この後のログ記録の説明を参照してください。

以下に、主なエラー文字列とその意味を示します。

API_REQUEST_ABORTED: API への HTTP リクエストが中止されました。
API_REQUEST_ERROR: API への HTTP リクエストでエラーが発生しました。
API_REQUEST_TIMEOUT: API がリクエストに応答しなかったため、タイムアウトが発生しました。
BAD_API_RESPONSE: API が失敗を示す状態コードの応答を返しました。
BAD_JSON_RESPONSE: API が、予期しない解析不能な JSON の応答を返しました。
DIALOG_CLOSED_BY_USER: ユーザが、購入を完了する前に決済ウィンドウを閉じました。通常、このエラーは無視できます。または取り消しを示すメッセージを表示することも可能です。このエラーは、mozPay() によって表示されます。
INCORRECT_USAGE: fxpay 関数の使い方が誤っています。詳細については、コンソールを参照してください。
INVALID_TRANSACTION_STATE: トランザクションが無効な状態にあるため、処理できません。
MISSING_XHR_PERMISSION: Web アプリに、systemXHR アプリ許可がありません。API リクエストを実行するには、このアプリ許可が必要です。
NOT_INITIALIZED: ライブラリが正しく初期化されていません。アクションが実行できません。init() を呼び出していないか、未修正の例外が存在する可能性があります。詳細については、コンソールを参照してください。
NOT_INSTALLED_AS_APP: このプラットフォームはアプリをサポートしていますが、アプリがデバイスにインストールされていません。ブラウザから直接アクセスされている可能性があります。
PAY_PLATFORM_UNAVAILABLE: このプラットフォームは、決済をサポートしていません。navigator.mozApps 名前空間または、mozPay() 関数が使用不可であるか、Apps.addReceipt メソッドが存在しない可能性があります。
TEST_RECEIPT_NOT_ALLOWED: ユーザがテストレシートを使用して製品の復元を試みましたが、フェイク製品が設定されていませんでした。
TRANSACTION_TIMEOUT: トランザクション状態を確認する HTTP リクエストがタイムアウトしました。
USER_CANCELLED: ユーザが購入をキャンセルしました。通常、このエラーは無視できます。または取り消しを示すメッセージを表示することも可能です。このエラーは、mozPay() によって表示されます。

また、コールバックが、アプリのエラー文字列のいずれか (INVALID_MANIFEST など) を受信することがあります。

ログ記録

標準設定では、fxpay は window.console を使用してすべてのログを記録します。console を別のロガーに変更する場合は、同じ window.console メソッドを実装する log としてオブジェクトを渡します。

fxpay.configure({log: myConsole});

設定

一部の内部変数は、fxpay.configure(overrides) を呼び出して設定できます。これを繰り返し呼び出した場合、上書きしない限り、古いキーが保持されます。

例:

fxpay.configure({apiTimeoutMs:3000});

上書きする場合は、以下を使用できます。

allowAnyAppReceipt: true に設定すると、他の開発者のアプリに対するレシートが無効としてマークされます。標準設定は、false です。
apiUrlBase: 内部 fxpay API のベース URL。標準設定は、https://marketplace.firefox.com です。
apiTimeoutMs: API リクエストがタイムアウトするまでの時間の長さ (秒)。標準設定は、10000 です。
apiVersionPrefix: apiUrlBase の末尾に追加され、正しい API バージョンにアクセスするパス。標準設定は、/api/v1 です。
fakeProducts: true の場合、fxpay.getProducts() を呼び出すと、テストに使用できるフェイク製品が返されます。詳細については、フェイク製品を参照してください。標準設定は、false です。
log: 内部的に使用する window.console と互換性のあるログオブジェクト標準設定は、window.console です。
receiptCheckSites: 購入レシートの検証を許可された一連のサイト。この値は、検証サービスの最上位レベルの URL です。URL パスを含める必要はありません。本番バージョンの Firefox Marketplace 以外を使用する場合のみ調整が必要です。標準設定は、['https://receiptcheck.marketplace.firefox.com'] です。

追加情報

fxPay is hosted GitHub の開発プロジェクト。プロジェクトには、ソースコードに加えて、サンプルアプリケーションが含まれています。