# コマースおよびカタログアイテムイベント

このガイドでは、Flutter SDK を使用してコマースおよびカタログ関連のユーザーインタラクションを Pushly に送信する方法を説明します。これらのイベントは、放棄されたカート通知、保存済みアイテムのリマインダー、収益のアトリビューション、カタログ駆動のレコメンデーションキャンペーンなどの機能を支えます。

以下で説明するイベントを送信する前に、Pushly Flutter SDK を読み込み、初期化しておく必要があります。

{% hint style="info" %}
以下の手順は、アイテムカタログ/フィードを当社チームに提供していることを前提としています。このプロセスの詳細については、アカウントマネージャーにお問い合わせください。
{% endhint %}

### サポートされているインタラクションの種類

Pushly は次のコマースおよびカタログインタラクションをサポートしています。

* **view\_item** – ユーザーがアイテム詳細ページを閲覧する
* **save\_item** – ユーザーがアイテムを保存またはお気に入り登録する
* **unsave\_item** – ユーザーが保存済みアイテムを削除する、またはお気に入り解除する
* **complete\_item** – ユーザーがアイテムを完了する
* **uncomplete\_item** – ユーザーが完了済みアイテムを削除する
* **rate\_item** – ユーザーがアイテムを評価する
* **unrate\_item** – ユーザーがアイテムから評価を削除する
* **add\_to\_cart** – ユーザーがアイテムをカートに追加する
* **update\_cart** – ユーザーがカートの内容または数量を変更する
* **purchase** – ユーザーが取引を完了する

各インタラクションでは、カタログ設定に応じて 3 種類の識別子タイプのいずれかを使用してアイテムを参照できます。

各アイテムには `id`が必要です。数量と評価は、特に明記されていない限り

{% hint style="danger" %}
以下のすべてのコードスニペットは、 **後に** SDK が初期化されてから実行する必要があります。
{% endhint %}

### アイテムを閲覧

ユーザーがアイテム詳細ページを閲覧したときにこのイベントを送信します。

{% tabs %}
{% tab title="Dart" %}

```dart
await PushSDK.UserProfile.viewItem(CatalogItem("ITEM_ID"));
```

{% endtab %}
{% endtabs %}

### アイテムを保存

ユーザーがアイテムを保存、お気に入り登録、またはブックマークしたときにこのイベントを使用します。これにより、保存済みアイテムのリマインダーキャンペーンが有効になります。

{% tabs %}
{% tab title="Dart" %}

```dart
await PushSDK.UserProfile.saveItem(CatalogItem("ITEM_ID"));
```

{% endtab %}
{% endtabs %}

### アイテムの保存を解除

ユーザーが保存リスト、お気に入り、またはブックマークからアイテムを削除したときにこのイベントを使用します。

{% tabs %}
{% tab title="Dart" %}

```dart
await PushSDK.UserProfile.unsaveItem(CatalogItem("ITEM_ID"));
```

{% endtab %}
{% endtabs %}

### アイテムを完了

ユーザーは、意図された体験を終えた後、そのアイテムを完了済みとしてマークします。

{% tabs %}
{% tab title="Kotlin" %}

```dart
await PushSDK.UserProfile.completeItem(CatalogItem("ITEM_ID"));
```

{% endtab %}
{% endtabs %}

### アイテムの完了を解除

アイテムの完了を取り消すには、このイベントを使用します。

{% tabs %}
{% tab title="Dart" %}

```dart
await PushSDK.UserProfile.uncompleteItem(CatalogItem("ITEM_ID"));
```

{% endtab %}
{% endtabs %}

### アイテムを評価

この `rate_item` イベントには任意の `rating` プロパティが含まれます。指定する場合、 `rating` は **0 から 100** までの **小数第1位まで**の数値である必要があります。整数値も有効です。

{% tabs %}
{% tab title="Dart" %}

```dart
await PushSDK.UserProfile.rateItem(CatalogItem("ITEM_ID", rating: 5));
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
この `rating` 値は製品のネイティブなスケールを反映する必要があります — ユースケースに適した任意の範囲を使用してください（例: 星評価なら 1～5、スコアなら 0～10、パーセンテージ風の評価なら 1～100）。唯一の要件は、その値が 0～100 の範囲内であり、小数第1位を超えないことです。
{% endhint %}

### アイテムの評価を解除

ユーザーがアイテムから評価を削除したときにこのイベントを使用します。

{% tabs %}
{% tab title="Dart" %}

```dart
await PushSDK.UserProfile.unrateItem(CatalogItem("ITEM_ID"));
```

{% endtab %}
{% endtabs %}

### カートに追加

ユーザーがアイテムをカートに追加するたびにこのイベントを送信します。Pushly は複数回の呼び出しにわたってカートの状態を蓄積します。

{% tabs %}
{% tab title="Dart" %}

```dart
await PushSDK.UserProfile.addToCart([
    CatalogItem("ITEM_ID", 2),
]);
```

{% endtab %}
{% endtabs %}

必要に応じて `add_to_cart` を何度でも呼び出して、訪問者のカート内のすべてのアイテムを追跡できます。購入されていない顧客のカート内の任意のアイテムに対して、放棄カート通知が送信される場合があります。

購入が行われると訪問者のカートは空になり、購入済みアイテムに関する通知は訪問者に送信されなくなります。 

### カートを更新

数量の調整やアイテムの削除など、ユーザーが購入を完了せずにカートを変更したときにこのイベントを使用します。

カートからアイテムを削除するには、 `update_cart` メソッドを現在の完全なカート情報（削除したアイテムを除く）とともに呼び出します:

{% tabs %}
{% tab title="Dart" %}

```dart
await PushSDK.UserProfile.updateCart([
    CatalogItem("ITEM_ID", 2),
]);
```

{% endtab %}
{% endtabs %}

または、カートが完全に空になった場合は空の配列を指定します:

{% tabs %}
{% tab title="Dart" %}

```dart
await PushSDK.UserProfile.updateCart([]);
```

{% endtab %}
{% endtabs %}

### 購入

チェックアウトが成功した後にこのイベントを送信します。これにより放棄カート状態がクリアされ、収益アトリビューションが有効になります。

{% tabs %}
{% tab title="Dart" %}

```dart
await PushSDK.UserProfile.trackPurchase(
      [CatalogItem("ITEM_ID", 2)],             // アイテム
      "ABC123",                                // purchase_id
      "19.99"                                  // price_value
);
```

{% endtab %}
{% endtabs %}

#### パラメータの順序

`trackPurchase(items, purchase_id, price_value)`

このメソッドは位置引数を使用するため、値はこの順序で渡す必要があります:

* `items`
* `purchase_id`
* `price_value`

#### 購入フィールド

* **price\_value** – ドメインに設定されている通貨での購入合計金額
* **purchase\_id** – 一意の注文識別子

もし `purchase` イベントがアイテムデータなしで送信された場合でも、Pushly は引き続きユーザーのカート状態をクリアします。

#### 通貨の取り扱い

`price_value` は、プラットフォームのドメイン設定でそのドメインに設定されている通貨で指定する必要があります。

すべての通貨で、小数点区切りにはピリオド（`.`）を使用してください。ロケールに関係なく、カンマは使用しないでください。

例:

* USD: `"344.33"`
* JPY: `"5000"`

### 必須フィールドの概要

* `id` はすべてのアイテムで必須です
* `quantity` は、カートまたは購入数量を追跡する場合にのみ必須です
* `rating` は、アイテムを評価する場合にのみ必須です

### 実装のベストプラクティス

イベントの取りこぼしを避けるため、ページライフサイクルの早い段階で SDK を初期化してください。

Pushly が行動を正しく関連付けられるよう、すべてのインタラクションタイプで一貫したアイテム ID を使用してください。

トリガー `purchase` 誤った放棄カート通知を避けるため、可能な限り信頼できる確認ステップからイベントを発火させてください。