This page is not available in English.

Please select another language.

はじめに

アチーブメントとはゲームごとに設定可能な概念で、各インストールユーザーが達成すべき出来事を表すオブジェクトです。 例えば次のような概念を指します。

• ゲーム内での隠しステージ1をクリアした
• あるミッションを100回クリアした

上記の定義は Mobage Developers にて追加することができ、定義の取得を行う API が Achievement API となります。
アチーブメントに対してのユーザーの達成状況を管理する API が User Achievement API になります。User Achievement API を利用すると、ユーザーの達成状況を取得・更新することが可能です。
 
このページでは、アチーブメントの設定方法・利用方法を説明していきます。
 
API の詳細については、以下のドキュメントをご参照ください。

• Achievement API
• User Achievement API

アチーブメントについて

 
アチーブメントを以下の項目ごとに説明していきます。

• アチーブメントの状態
• アチーブメントの種類
• アチーブメントのステップ
• アチーブメントポイント
• アチーブメントの繰り返し
• アチーブメントの状態遷移

アチーブメントの状態

アチーブメントには、ユーザーごとにアチーブメントの状態 (state) が存在します。User Achivement オブジェクトの state にあたる状態を表す文字列になります。例えば、アチーブメントが未達成の場合には "REVEALED"、達成済みの場合には "UNLOCKED" のように達成状況にあわせて state が遷移します。各状態についての詳細は以下になります。

アチーブメントの種類

アチーブメントの種類は、Achievement オブジェクトの type を表します。アチーブメントの type には 「1 回で達成」(STANDARD) と「複数回で達成」 (INCREMENTAL) の 2 種類があり、前項の例に当てはめると以下のようになります。

Achievement オブジェクトの type プロパティ内の値は、"STANDARD" もしくは "INCREMENTAL" になります

STANDARD のアチーブメントは達成しているかしていないかという状態のみ (0 or 1) を表すのに対して、INCREMENTAL のアチーブメントは達成までに必要なステップ数 (totalSteps) が存在します。
INCREMENTAL のアチーブメントは達成状況を User Achievement API を使って増加させていくことにより、ユーザーごとの steps を増加させ、それがアチーブメントの totalSteps まで達した際に、 UNLOCKED した事になります。（増加させていくだけでなく、減少させることも可能です）

詳細は、User Achievement API ドキュメントの"任意のユーザーの User Achievement オブジェクトを Achievement ID と増減値（Increment / Decrement）を指定して作成・更新する (POST)" をご確認下さい。

アチーブメントのステップ

Achievement オブジェクトの type が INCREMENTAL に設定されている時のみ使用できる概念です。User Achievement オブジェクトの steps にあたり、User Achievement API を利用して、steps の更新、steps の増減を行うことができます。

アチーブメントポイント

あるユーザーがアチーブメントを達成した場合に、アチーブメントに設定されたアチーブメントポイントの値がユーザーに対して付与されます。Achievement オブジェクトの point にあたります。この point は間接的にプラットフォーム内でのプレイヤーの格付け等に用いられます。

point の絶対値に特に意味は無く、アチーブメントごとの達成難易度や価値に応じて設定して下さい。原則として個々のアチーブメントに配分出来る point の最大値は 10000 が最大となっています。
 

アチーブメントの繰り返し

一度、state が UNLOCKED になったアチーブメントは再度 UNLOCKED に設定する事は出来ませんが、Mobage Developers に設定されている繰り返し設定が「はい」となっている (repeatable = true) アチーブメントに関しては再度 UNLOCKED にする事が出来ます。その際には、 UNLOCKED になる度にそのユーザーにポイントが付与されるようになります。
 

アチーブメントの状態遷移

アチーブメントでは、「state の更新」や「steps の更新/増減」によって、状態が変化します。status 遷移の概要については以下の図をご確認下さい。

アチーブメントには、Mobage Developers で上記 state の初期値をアチーブメントごとに defaultState として設定することができます。HIDDEN、REVEALED、UNLOCKED いずれにおいても設定が可能です。
state の遷移は UserAchievement API での update により、 HIDDEN → REVEALED → UNLOCKED と変化していくのが基本です。UNLOCKED → REVEALED → HIDDEN のような逆行する state 設定はできません。
 
以下の方法で、state を遷移させることができます。

• HIDDEN → REVEALED
  • User Achievement API で state を REVEALED へ更新する。
• REVEALED → UNLOCKED
  • User Achievement API で state を UNLOCKED へ更新する。
  • User Achievement API で steps を totalSteps を超える値で更新する。 (type=INCREMENTAL のみ)
  • User Achievement API で totalSteps を超えるまで steps を Increment する。 (type=INCREMENTAL のみ)
• UNLOCKED → UNLOCKED (repeatable = true の場合のみ)
  • User Achievement API で state を UNLOCKED へ更新する。
    • User Achievement オブジェクトの numOfUnlocked が 1 増加します。
  • User Achievement API で steps を totalSteps を超える値で更新する。 (type=INCREMENTAL のみ)
  • User Achievement API で totalSteps を超えるまで steps を Increment する。 (type=INCREMENTAL のみ)

また、repeatable = true の場合、totalSteps を超えた steps で更新する場合、steps や numOfUnlocked は以下のように変化します。

• totalSteps を超えた steps で更新する場合
  • steps / totalSteps 分、numOfUnlocked が 増加します。 (整数)
  • steps / totalSteps のあまり分の steps に設定されます。 (整数)
• totalSteps を超える steps で Increment する場合 (Increment)
  • (現在の steps + Increment する steps) / totalSteps の小数点を切り下げた数値分、numOfUnlocked が増加します。 (整数)
  • (現在の steps + Increment する steps) / totalSteps のあまり分、steps が増加します。 (整数)
• 0 を下回るようになる steps で Increment する場合 (Decrement)
  • (現在の steps + Increment する steps) / totalSteps の小数点を切り上げた数値分、numOfUnlocked が増加します。 (整数)
  • totalSteps - (現在の steps + Increment する steps) / totalSteps のあまり分、steps が増加します。 (整数)
     

    steps の更新には、負の値は使用できません。

    User Achievement API の Increment/Decrement 機能では、endpoint /@self/achievements{/appId,achievementId}/increment に対して、正負の値を指定して、増減値を決定するため、上記ではあえて数値分"Increment"や"増加"として表現を統一しています。

    totalSteps を上回る steps で 更新した場合、totalSteps と同じ値に丸められます。

    0 を下回る steps で Increment する場合に、numOfUnlocked が 1 を下回って、UNLOCKED から REVEALED に遷移するようなことはありません。numOfUnlocked の下限は 1 であり、steps の下限は 0 ですので、それを下回る設定の場合は、自動的に下限値の値になります。

     
    具体的な例としては、以下の表をご確認下さい。

    ケース	現在の steps の値	現在の numOfUnlocked の値	totalSteps の値	設定する値	増加後の steps の値	増加/減少後の numOfUnlocked の値
    現在の steps を totalSteps と同じ steps で更新する場合	20	2	100	steps を 100 で更新する	0	3
    現在の steps を totalSteps を超えた steps で更新する場合	20	2	100	steps を 1000 で更新する	0	3
    現在の steps を totalSteps を超えて Increment する場合	20	2	100	120 で Increment する	40	3
    現在の steps を totalSteps を超えて Increment する場合	20	2	100	190 で Increment する	10	4
    現在の steps が 0 を下回るような steps で Increment する場合	20	2	100	-60 で Increment する	60	1
    numOfUnlocked が 1 の場合、かつ現在の steps を、0 を下回る steps で Decrement する場合	20	1	100	-60 で Increment する	0	1
    numOfUnlocked が 1 の場合、かつ現在の steps を、0 を下回る steps で Decrement する場合	10	3	100	-120 で Increment する	90	1

     
     

    アチーブメントの設定

     
    アチーブメントを利用するためには、Mobage Developers へアチーブメントの登録が必要になります。

    Sandbox に登録したアチーブメントを本番環境に反映させるためには、本番環境に反映させるためには をご確認下さい。

     
    アプリケーション管理の「アプリケーション詳細」より、以下の図の左下の「共通設定」より「アチーブメント設定」のリンクをクリックします。
     
    
     
    以下のような設定画面が表示されますので、「新規作成」ボタンをクリックします。
     
    
     
    以下の様な設定画面が、アチーブメントの種類毎に表示されます。
     
• 「1回で達成」(STANDARD) を選んだ場合
  
• 「複数回で達成」(INCREMENTAL) を選んだ場合
  
  各項目について解説します。

アチーブメント識別子

アチーブメントを識別する文字列を入力します。Achievement オブジェクトの id にあたる識別子となります。

アチーブメント名

アチーブメントの名前を表す文字列を入力します。Achievement オブジェクトの name にあたる文字列となります。
 

種類

"1回で達成" (STANDARD) もしくは、"複数回で達成" (INCREMENTAL) のどちらかを設定できます。Achievement オブジェクトの type にあたる設定となります。詳細はアチーブメントの種類をご確認下さい。
"複数回で達成"に設定された場合は、「達成ステップ数」および「ステップの単位」の設定ができるようになります。
 

達成ステップ数 (種類が複数回で達成に設定されている時のみ)

上記、アチーブメントの種類 が "複数回で達成" (INCREMENTAL) の時のみ設定できる、達成までの値です。Achievement オブジェクトの totalSteps にあたる数値となります。1〜10000 までの値を設定可能です。詳細はアチーブメントの種類をご確認下さい。
 

ステップの単位 (種類が複数回で達成に設定されている時のみ)

上記、アチーブメントの種類 が "複数回で達成" (INCREMENTAL) の時のみ設定できる、プラットフォーム側での表示の際に用いられる進捗を表す単位を記載します。Achievement オブジェクトの stepFormat にあたる文字列です。表示の際に使用される文字列で、半角 32 文字まで設定可能です。例えば百分率で表現したければ totalSteps に100 を指定し、stepFormat に "%" を指定します。

2013/10/3 現在は、プラットフォーム側に表示されることはありません。

アチーブメントポイント

あるユーザーがアチーブメントを達成した場合に、取得できるポイントを 1〜 10000 の範囲で設定できます。Achievement オブジェクトの point にあたる数値となります。この point は間接的にプラットフォーム内でのプレイヤーの格付け等に用いられますが、User Achievement API 等で取得することはできません。達成難易度やアチーブメントの価値に応じて設定して下さい。

2013/10/3 現在は、プラットフォーム側に表示されることはありませんが、今後表示される可能性があります。

繰り返し

繰り返し設定をするかどうかを選択できます。Achievement オブジェクトの repeatable にあたり、「はい」の場合は true、「いいえ」の場合は false になります。繰り返し設定が「はい」の場合は、state が一度 UNLOCED になった場合にも繰り返し UNLOCKED にすることが可能です。繰り返し設定が「いいえ」の場合は、state が一度 UNLOCKED になった場合には、続けて UNLOCKED にすることはできなくなります。
 

デフォルト状態

アチーブメントの state のデフォルト値を設定することができます。Achivement オブジェクトの defaultState にあたる値となります。デフォルト値を設定すると state の初期状態を決定できます。詳細は、アチーブメントの状態とアチーブメントの状態遷移をご確認下さい。
 

解除(UNLOCKED) のアイコン設定と説明文の設定

アチーブメントの state が UNLOCKED の場合のアイコンと説明文を設定します。アイコンは、Achievement オブジェクトの unlockedIconUrls、説明文は unlockedDescription にあたります。
 
アイコンは 176 x 176 の PNG 形式でアップロードし、アップロードすると自動的に以下の以下の 5 種類の画像が生成されます。unlockedIconUrls の各プロパティの値についても併記しています。
 

 
生成された 5 種類の画像は Achievement API で取得した画像の参照先 URL で取得することが可能です。
 

未解除(REVEALED) のアイコン設定と説明文の設定

アチーブメントの state が REVEALED の場合のアイコンと説明文を設定します。アイコンは、Achievement オブジェクトの revealedIconUrls、説明文は revealedIconUrls にあたります。

アイコンは 176 x 176 の PNG 形式でアップロードし、アップロードすると自動的に以下の以下の 5 種類の画像が生成されます。revealedIconUrls の各プロパティの値についても併記しています。

生成された 5 種類の画像は Achievement API で取得した画像の参照先 URL で取得することが可能です。

上記、設定が完了し、OK ボタンをクリックすると Sandbox 環境へのアチーブメントの登録が完了します。
 

API でできること

Achievement API でできることは、以下の 2 種類になります。

• ゲームに紐付いた Achievement コレクションを取得する
• ゲームに紐付いた Achievement オブジェクトを識別子を指定して取得する

User Achievement API でできることは以下になります。

• 任意のユーザーのアプリ内で作成・更新した事のある User Achievement コレクションを取得する (GET)
• 任意のユーザーの User Achievement コレクションを Achievement ID を指定して取得する (GET)
• 任意のユーザーの User Achievement オブジェクトを Achievement ID を指定して作成・更新する (PUT)
  • 任意のユーザーの User Achievement オブジェクトの state の更新
  • 任意のユーザーの User Achievement オブジェクトの steps の更新
• 任意のユーザーの User Achievement オブジェクトを Achievement ID と steps の増減値（Increment / Decrement）を指定して作成・更新する (POST)

上記 API の詳細は、以下のドキュメントをご確認下さい。

• Achievement API
• User Achievement API

• Achievement API
• User Achievement API

本番環境に反映させるためには

 
Sandbox 環境に登録されたアチーブメントを本番環境で有効にするためには、各アチーブメントの右上に表示されている「本番環境で有効にする」ボタンをクリックする必要があります。クリックすると、本番環境で有効化され、Achievement API が本番環境で使用可能となります。
 

 
本番環境で有効になると、以下のように、Sandbox 環境の内容が、Production 環境（本番環境）にコピーされます。
 

 
上記状態で編集ボタンをクリックすると、Sandbox 環境の情報を編集することができます。編集後に現在有効化している本番環境の内容と差異がある場合には、右上の部分に表示されます。
 
Sandbox 環境で修正された情報を本番環境に反映するためには、右上の「本番環境に反映」ボタンをクリックします。
 

 

本番環境に直接反映することはできません

更新履歴 

• 2013/10/18
  • 本番環境リリースに伴い、各項目追記
• 2013/10/03
  • 新規作成