アイテムカタログカタログ個人用設定

このチュートリアルでは、次のことを説明します：

• ユーザー側で作成した属性を使用してカタログをパーソナライズする方法（ペイステーションアクセストークンを使用してユーザーを認証するパートナー向け）
• JSONモードで属性検証ルールを指定し、エクソーラ側でユーザーに属性を追加する方法（エクソーラログインを使用してユーザーを承認するパートナー向け）
• カタログの表示ルールを作成する方法
• 異なる属性値を持つユーザーのアイテムカタログを取得する方法

前提条件

開始する前に、以下のことを確認してください：

• ゲーム内アイテムまたはゲームキーのカタログを作成し、個人用設定を構成します。
• ユーザー属性セクションを探索しました（エクソーラログインを使用してユーザーを認証するパートナー向け）。
• ユーザーデータベース > ユーザーセクションのログインプロジェクト設定で、属性を追加できるユーザーを追加しました（エクソーラログインを使用してユーザーを認証するパートナー向け）。

ペイステーションアクセストークンを使用してユーザーを認証する個人用設定

ペイステーションアクセストークンを使用してユーザーを認証する場合、トークン取得時に属性を渡すことができます。この場合、以下のようにして個人用設定を設定します：

1. システムで属性を作成します。
2. システム内のユーザーに属性を追加します。
3. ゲーム内のユーザーの属性値が変更されたときに属性値を更新するロジックを実装します。
4. 属性を使用してカタログ表示ルールを作成します。
5. ペイステーションアクセストークンを取得するときに属性を渡します。
6. 受け取ったトークンは、アイテムカタログリクエスト方法で使用します。

エクソーラを使用してユーザーを認証するカタログ個人用設定

エクソーラログインを使ってユーザーを認証する場合、

1. エクソーラ側でユーザー属性のJSONスキーマを作成し、その中で属性を指定する必要があります（任意）。

2. Login APIを使用して、ユーザーに属性を追加し、属性値を更新します。
3. 作成した属性を使用してカタログ表示ルールを作成します。
4. ユーザーのJWTの取得を実装します。JWTを取得するためのメソッドのリストは、この例にあります。
5. アイテムカタログを要求するためのメソッドで受信したトークンを使用します。

ユーザに属性を追加するには、いくつかの方法があります：

• 属性更新メソッドを使用します：
  • サーバーからユーザーの属性を更新する
  • サーバーからユーザーの読み出し専用属性を更新する

1. これらのメソッドを使用して、ユーザーに属性を追加し、属性値を更新します。カタログをパーソナライズするには、属性値を最新の状態に保つ必要があります：ゲーム内のユーザーのために属性値が変更されたときにエクソーラの属性値を更新します。

1. 例：ユーザーは、新しいレベルに到達し、タスクを完了し、購入することができます。

1. 1つの属性と複数の属性の値を同時に更新できます。JSONスキーマで必須として指定された属性は例外です。必須属性値を指定しないと、属性更新APIメソッドを呼び出すことができません。

• カスタムIDによる認証するメソッドを使用する場合は、ユーザーを認証する際に実際の属性値を直接渡します。このメソッドでは、ユーザー属性の現在の値を配列で渡すことができます。

個人用設定の設定例

この例では、カタログ個人用設定の設定方法を示しています。MyTestGameを購入したユーザーのみに表示される「中型クリスタルセット」アイテムです。

属性スキーマの作成

• 属性“game”、タイプ“string” — ユーザーが購入したゲームの名前。“game”属性は必須とマークされています。“game”属性を渡さなければ、属性更新メソッドを呼び出すことはできません。

• 属性“purchase_number”、タイプ“integer” — ユーザー購入数。

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"title": "Example",
	"description": "JSON Schema description.",
	"properties": {
		"game": {
			"description": "Name of the game played by a user.",
			"type": "string"
		},
		"purchase_number": {
			"description": "The number of purchases the user made.",
			"type": "integer"
		}
	},
	"additionalProperties": false,
	"required": [
		"game"
	],
	"type": "object"
}

ユーザーに属性を追加する

サーバーからユーザーの読み出し専用属性を更新するメソッドを使用して、ユーザーデータベースからユーザーに属性を追加します。

サーバーからユーザーの読み出し専用属性を更新するメソッドで、以下のことを指定する必要があります：

• サーバートークン。
• ユーザー属性値。
• user_id — ユーザーデータベース > ユーザーセクションのアドミンページのログインプロジェクトの設定で指定されたユーザー識別子。
• publisher_id ― マーチャントIDは以下の場所で指定されます：
  • 会社設定 > 会社セクション。
  • アドミンページページのブラウザアドレスバーのURL。URLは以下の形式があります：https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>。
• publisher_project_id — アドミンページでプロジェクト名の側に表示されるプロジェクトID。

JWTを生成するメソッドを使用して、サーバートークンを事前に取得します。

次に、サーバーからユーザーの読み出し専用属性を更新するメソッドに進みます。

attributesの配列を持つリクエスト本文の書式は次のようになります：

{
  "attributes": [
    {
      "key": "game",
      "permission": "private",
      "value": "MyTestGame"
    },
 {   
     "key": "purchase_number",
      "permission": "private",
      "value": "30"
    }

  ],
  "publisher_id": 000000,
  "publisher_project_id": 000000
}

リクエストを実行した結果、属性を持っていないユーザーは、指定された値を持つ属性を持つようになります：

カタログの表示ルールを作成

MyTestGameを購入したユーザーにのみ、「中型クリスタルセット」アイテムを表示するルールを設定します。

操作するには：

1. アドミンページで、「ストア > カタログ管理 > カタログ表示ルール」に移動します。
2. 「ルールを作成する」をクリックして、以下の必須なフィルドを完了します：
   1. ユーザー属性フィルドでの属性キー — game
   2. た — string
   3. 比較演算子 — equal to
   4. 値 — MyTestGame

3. 条件を満たした場合に表示するアイテムを指定します。下記の例では、MyTestGameを所有しているユーザーに対して、「中型クリスタルセット」を表示しています。

4. ルールをチェックし、アクティブにして保存します。

トークンの取得

エクソラログインJWTの取得

• ユーザー名とパスワードによる認証
• ソーシャルプロバイダー経由の認証
• メールアドレスによるパスワードレス認証
• 電話番号によるパスワードレス認証
• デバイスID経由の認証
• カスタムIDによる認証
• JWTまたはOAuth.2.0メソッドグループからユーザートークンを取得するその他のメソッド

ペイステーションアクセストークンの取得

必須の属性を持つペイステーションアクセストークンを取得します。これを行うには、トークンをを作成するメソッドのattributesオブジェクトで“game”: “MyTestGame”を渡す必要があります。

リクエスト本文の例：

{
  "settings": {
    "currency": "USD",
    "language": "en",
    "project_id": 000001,
    "ui": {
      "size": "medium"
    }
  },
  "user": {
    "email": {
      "value": "email@example.com"
    },
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    },
    "attributes": {
      "game": "MyTestGame"
    }
  }
}

アイテムカタログの取得

エクソーラログインJWTを使用したアイテムカタログの取得

MyTestGameの値を持つgame属性を追加したユーザーのトークンを使用してカタログを取得します。これを行うには、仮想アイテムリストを取得するメソッドで以下を指定します：

• 認証ヘッダーの取得したユーザーJWT
• パスパラメータとしてのアドミンページのプロジェクトID

応答には3つのアイテムが含まれます：

• エンパイアキー
• 小型クリスタルパック
• 個人用設定ルールが構成された中型クリスタルセット

"attributes": [
{
    "attr_type": "server",
    "key": "game",
    "permission": "private",
    "value": "OtherGame",
    "read_only": true
 },
{
    "attr_type": "server",
    "key": "purchase_number",
    "permission": "private",
    "value": "30",
    "read_only": true
  }
]

取得したトークンを使って仮想アイテムリストを取得するメソッドを実行すると、2つのアイテムが返されます：「エンパイアキー」と「小型クリスタルパック」。個人用設定ルールがが適用された「個人用設定ルール」セットは、応答に含まれません。

比較のために、game属性にMyTestGame値を渡します。

これは、ゲームMyTestGameを持つユーザのカスタムIDによる認証するメソッドのattributes配列です：

"attributes": [
{
    "attr_type": "server",
    "key": "game",
    "permission": "private",
    "value": "MyTestGame",
    "read_only": true
 },
{
    "attr_type": "server",
    "key": "purchase_number",
    "permission": "private",
    "value": "30",
    "read_only": true
  }
]

仮想アイテムリストを取得するメソッドでアイテムカタログを要求する際に、取得したトークンを指定します。

その結果、「中型クリスタルセット」が応答に含まれます。

ペイステーションアクセストークンを使用したアイテムカタログの取得

パーソナライズされたアイテムカタログを取得するには、仮想アイテムリストを取得するメソッドで以下を指定する必要があります：

• 認証ヘッダーの取得したペイステーションアクセストークン
• パスパラメータとしてのアドミンページのプロジェクトID

応答には3つのアイテムが含まれます：

• エンパイアキー
• 小型クリスタルパック
• 個人用設定ルールが構成された中型クリスタルセット

ユーザーがgame属性にMyTestGameを指定していない場合、アイテムカタログ取得時のレスポンスをテストすることができます。

ペイステーションアクセストークンを受け取ったら、attributesオブジェクトを削除し、仮想アイテムを取得するリストメソッドを使用してアイテムカタログを再度リクエストします。今度は、応答にミディアムクリスタル・セットが含まれません：