====== 課金実装 ====== ADV.MASTERはFANZA GAMES、にじGAME、animateGAMESの各プラットフォーマーと課金連携しており、簡単な設定とスクリプトだけで各プラットフォーマーの課金の仕組みを利用することができます。 ===== 課金タイプ ===== 課金は課金アイテムIDを設定して、paymentタグにて実行されます。課金アイテムIDには2つのタイプがあります。 1. シナリオチケットタイプ\\ シナリオをブロック分けし、各ブロックの入り口で課金チェックをして未課金であれば課金処理を実行します。一度課金したシナリオチケットはその後も消えることなく継続して保持されます。\\ 2. アイテム課金タイプ\\ ゲーム中に消費されるアイテムなど、繰り返し課金する場合に使用します。 ===== 実装方法 ===== ==== スクリプト記述概要 ==== 1. f.js_payment_itemId変数に課金アイテムIDを設定する\\ 2. paymentタグでプラットフォーマーの課金画面に遷移する\\ 3. 課金が完了すると「tf.js_pay_itemId_<課金アイテムID>」に1が代入される\\ ※アイテム課金タイプの場合は2度目以降の課金で当該変数がインクリメント（+1）されます。\\ ※シナリオチケットタイプの場合、同一の課金アイテムIDで2回以上の課金はできません。課金済みの課金アイテムIDで課金処理を行うとシステムが重複を検知し課金エラーとなります。課金処理をする前に「tf.js_pay_itemId_<課金アイテムID>」を検査して課金処理に入ってください。後述の「[[課金実装#スクリプトサンプル（シナリオチケットタイプ）|スクリプトサンプル（シナリオチケットタイプ）]]」参照\\ ==== 課金アイテム画像 ==== プラットフォーマーの課金画面に表示するアイテム画像をpngフォーマットでfreeフォルダに格納します。\\ 画像のサイズに関してはプラットフォーマーの仕様に準じます。\\ ==== 課金情報ファイルの設定 ==== ゲーム中で使用するすべての課金に対して、課金アイテムIDや課金タイプなどの課金情報を課金情報ファイル（js_payment.properties）に記述し、infoフォルダに格納します。\\ |文字コード|SJIS| |格納場所|infoフォルダ内| |フォーマット|json| ^パラメータ名^内容^例^ |%%------------%%|課金アイテムID|item01| |itemName|課金アイテム名。[[課金実装#課金画面へ遷移|課金画面に表示される]]|花子ルート| |unitPrice|課金金額（税込み）|200| |quantity|数量（常に1固定）|1| |imageUrl|課金イメージ画像ファイル名。[[課金実装#課金画面へ遷移|課金画面に表示される]]|hoge.png| |description|課金アイテム説明文。[[課金実装#課金画面へ遷移|課金画面に表示される]]|花子ルートのシナリオチケットです| |type|課金タイプ\\ 0:シナリオチケットタイプ、1:アイテム課金タイプ|0| |例．課金アイテムIDを2つ設定する場合\\ {\\ 　%%"%%ticket01%%"%%:{\\ 　　%%"%%itemName%%"%%:%%"%%シナリオチケット１%%"%%,\\ 　　%%"%%unitPrice%%"%%:%%"%%90%%"%%,\\ 　　%%"%%quantity%%"%%:%%"%%1%%"%%,\\ 　　%%"%%imageUrl%%"%%:%%"%%hoge.png%%"%%,\\ 　　%%"%%description%%"%%:%%"%%シナリオチケット１です%%",%%\\ 　　%%"%%type%%"%%:%%"%%0%%"%%\\ 　}\\ 　,\\ 　%%"%%item01%%"%%:{\\ 　　%%"%%itemName%%"%%:%%"%%アイテム１%%"%%,\\ 　　%%"%%unitPrice%%"%%:%%"%%200%%"%%,\\ 　　%%"%%quantity%%"%%:%%"%%1%%"%%,\\ 　　%%"%%imageUrl%%"%%:%%"%%hoge2.png%%"%%,\\ 　　%%"%%description%%"%%:%%"%%アイテム課金です%%"%%,\\ 　　%%"%%type%%"%%:%%"%%1%%"%%\\ 　}\\ }| ==== スクリプトサンプル（シナリオチケットタイプ） ==== 課金アイテムIDをticket01とした場合 |;課金済みかどうかを検査\\ @if exp="tf.js_pay_itemId_ticket01 != 1"\\ ;当該シナリオチケット未課金なので課金する\\ ;課金処理が必要な旨をユーザーに提示\\ @link storage=title.sc\\ チケット購入しない（タイトル画面に戻る）\\ @endlink\\ @link\\ チケット購入画面にいく\\ @endlink\\ @s\\ ;課金するを選択したので課金処理実施\\ @eval exp="f.js_payment_itemId = 'ticket01'"\\ @payment place="opensocial"\\ @endif| ■課金後\\ 課金以降はゲームを再起動しても、常に「tf.js_pay_itemId_ticket01」に1が自動的に入るので、課金ポイントに来たら上記サンプルのように「tf.js_pay_itemId_ticket01」をifタグで検査して処理を進めます。 ==== スクリプトサンプル（アイテム課金タイプ） ==== 課金アイテムIDをitem01とした場合 |@link storage=hoge.sc\\ アイテム追加購入しない\\ @endlink\\ @link\\ アイテム追加購入する\\ @endlink\\ @s\\ @eval exp="f.js_payment_itemId = 'item01'"\\ @payment place="opensocial"| ■課金後\\ 「tf.js_pay_itemId_item01」に1が加算されます。課金以降はゲームを再起動しても「tf.js_pay_itemId_item01」の値は変わりません。evalタグで値を変更してもゲームを再起動すると元に戻ります。したがって残りのアイテム数は、使用したアイテム数をシステム変数に保管することで取得することになります。\\ 例えば、課金アイテムID「item01」の一回の課金が対応するアイテムを5個付与する仕様で、使用したアイテム数をsf.item01_use変数で管理したとすると、残アイテム数は「tf.js_pay_itemId_item01 × 5 - sf.item01_use」で算出します。 |スクリプト例\\ ;アイテム消費時\\ @eval exp="sf.item01_use += 1"\\ \\ ;アイテム残量検査時\\ @if exp="0 < tf.js_pay_itemId_item01 * 5 - sf.item01_use"\\ ;アイテム残数あり\\ @endif| ===== 課金画面からの戻り ===== プラットフォーマーの課金画面からADV.MASTERへ戻る際は、place=-2がロードされ、「tf.jsNextStartStatus」に課金結果が入ります。したがって、課金後の画面から戻ってほしい箇所に予めplace=-2でsaveをしておきます。 |スクリプト例：\\ @save place=-2\\ @if exp="tf.jsNextStartStatus == '1'"\\ ;購入後処理(課金した)\\ @elsif exp="tf.jsNextStartStatus == '2'"\\ ;購入後処理(課金しなかった)\\ @else\\ ;課金後ではない\\ @endif\\ ;tf.jsNextStartStatusをリセット\\ @eval exp="tf.jsNextStartStatus = '-1'"| ===== デバッグ（課金情報消去） ===== 課金を初期状態に戻すには「f.js_payment_itemId」に「debug_all_paid_delete」を設定してpaymentタグを実行します。\\ ※課金を初期化すると全てのシステム変数も消去されます。 |@if exp="tf.debugMode == '1'"\\ @link target=*delete\\ 課金消去する\\ @endlink\\ @link target=*hoge\\ 課金消去しない\\ @endlink\\ @s\\ @endif\\ \\ *delete\\ @eval exp="f.js_payment_itemId = 'debug_all_paid_delete'"\\ @payment place="opensocial"\\ \\ *hoge\\ …| ===== ユーザーからたみた課金の流れイメージ例 ===== ^　　^^ |1.課金箇所到達|{{:課金_1.png?nolink&400|}}| |{{anchor:課金画面へ遷移}}2.課金画面へ遷移|{{:課金_2.png?nolink&400|}}| |3.課金完了後ゲーム画面へ|{{:課金_3.jpeg?nolink&400|}}| ===== その他 ===== プラットフォーマーによって仮想通貨の呼称（コイン、ポイント等）が違うため、課金画面に遷移する前に表示する画像を差し替えることがあります。\\ その際は[[備え付け変数#kagprefixopensocial|kag.prefixOpensocial]]を利用して使用する画像への差し替えを制御します。