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

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

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

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

### サポートされるインタラクションタイプ

Pushlyは、以下のCommerceおよびカタログ操作をサポートしています:

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

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

### アイテム識別子の種類

すべてのインタラクションには、以下のいずれかのトップレベル配列が含まれます:

* **products** – 標準的なEコマース商品カタログ項目
* **events** – イベントベースのカタログ項目（例: チケット制コンテンツ）
* **recipes** – レシピまたはコンテンツベースのカタログ項目

1回のインタラクション呼び出しにつき、含める識別子の種類は1つだけにしてください。

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

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

### アイテムを表示

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

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

```
pushly('view_item', {
    "products": [
        {
            "id": "PRODUCT_ID"
        }
    ]
});
```

{% endtab %}

{% tab title="Events" %}

```
pushly('view_item', {
    "events": [
        {
            "id": "EVENT_ID"
        }
    ]
});
```

{% endtab %}

{% tab title="Recipes" %}

```
pushly('view_item', {
    "recipes": [
        {
            "id": "RECIPE_ID"
        }
    ]
});
```

{% endtab %}
{% endtabs %}

### アイテムを保存

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

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

```
pushly('save_item', {
    "products": [
        {
            "id": "PRODUCT_ID"
        }
    ]
});
```

{% endtab %}

{% tab title="Events" %}

```
pushly('save_item', {
    "events": [
        {
            "id": "EVENT_ID"
        }
    ]
});
```

{% endtab %}

{% tab title="Recipes" %}

```
pushly('save_item', {
    "recipes": [
        {
            "id": "RECIPE_ID"
        }
    ]
});
```

{% endtab %}
{% endtabs %}

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

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

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

```
pushly('unsave_item', {
    "products": [
        {
            "id": "PRODUCT_ID"
        }
    ]
});
```

{% endtab %}

{% tab title="Events" %}

```
pushly('unsave_item', {
    "events": [
        {
            "id": "EVENT_ID"
        }
    ]
});
```

{% endtab %}

{% tab title="Recipes" %}

```
pushly('unsave_item', {
    "recipes": [
        {
            "id": "RECIPE_ID"
        }
    ]
});
```

{% endtab %}
{% endtabs %}

### アイテムを完了

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

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

```
pushly('complete_item', {
    "products": [
        {
            "id": "PRODUCT_ID"
        }
    ]
});
```

{% endtab %}

{% tab title="Events" %}

```
pushly('complete_item', {
    "events": [
        {
            "id": "EVENT_ID"
        }
    ]
});
```

{% endtab %}

{% tab title="Recipes" %}

```
pushly('complete_item', {
    "recipes": [
        {
            "id": "RECIPE_ID"
        }
    ]
});
```

{% endtab %}
{% endtabs %}

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

アイテムの完了状態を元に戻すには、このイベントを使用します。

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

```
pushly('uncomplete_item', {
    "products": [
        {
            "id": "PRODUCT_ID"
        }
    ]
});
```

{% endtab %}

{% tab title="Events" %}

```
pushly('uncomplete_item', {
    "events": [
        {
            "id": "EVENT_ID"
        }
    ]
});
```

{% endtab %}

{% tab title="Recipes" %}

```
pushly('uncomplete_item', {
    "recipes": [
        {
            "id": "RECIPE_ID"
        }
    ]
});
```

{% endtab %}
{% endtabs %}

### アイテムを評価

「 `rate_item` イベントには、任意の `rating` プロパティが含まれます。\
指定する場合、 `rating` は0から100までの数値である必要があり、 **0〜100** の範囲内で、 **小数点以下1桁まで**です。整数値も有効です。\
 `rating` が省略されている場合、イベントは有効です。\
無効な `rating` 値により、SDKは **イベントを拒否し、送信しません**.

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

```
pushly('rate_item', {
    "products": [
        {
            "id": "PRODUCT_ID",
            "rating": 5,
        }
    ]
});
```

{% endtab %}

{% tab title="Events" %}

```
pushly('rate_item', {
    "events": [
        {
            "id": "EVENT_ID",
            "rating": 5,
        }
    ]
});
```

{% endtab %}

{% tab title="Recipes" %}

```
pushly('rate_item', {
    "recipes": [
        {
            "id": "RECIPE_ID",
            "rating": 5,
        }
    ]
});
```

{% endtab %}
{% endtabs %}

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

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

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

```
pushly('unrate_item', {
    "products": [
        {
            "id": "PRODUCT_ID"
        }
    ]
});
```

{% endtab %}

{% tab title="Events" %}

```
pushly('unrate_item', {
    "events": [
        {
            "id": "EVENT_ID"
        }
    ]
});
```

{% endtab %}

{% tab title="Recipes" %}

```
pushly('unrate_item', {
    "recipes": [
        {
            "id": "RECIPE_ID"
        }
    ]
});
```

{% endtab %}
{% endtabs %}

### カートに追加

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

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

```
pushly('add_to_cart', {
    "products": [
        {
            "id": "PRODUCT_ID",
            "quantity": 1
        }
    ]
});
```

{% endtab %}

{% tab title="Events" %}

```
pushly('add_to_cart', {
    "events": [
        {
            "id": "EVENT_ID",
            "quantity": 1
        }
    ]
});
```

{% endtab %}
{% endtabs %}

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

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

### カートを更新

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

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

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

```
pushly('update_cart', {
    "products": [
        {
            "id": "PRODUCT_ID",
            "quantity": 3
        }
    ]
});
```

{% endtab %}

{% tab title="Events" %}

```
pushly('update_cart', {
    "events": [
        {
            "id": "EVENT_ID",
            "quantity": 3
        }
    ]
});
```

{% endtab %}
{% endtabs %}

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

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

```
pushly('update_cart', {
    "products": []
});
```

{% endtab %}

{% tab title="Events" %}

```
pushly('update_cart', {
    "events": []
});
```

{% endtab %}
{% endtabs %}

### 購入

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

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

```
pushly('purchase', {
    "products": [
        {
            "id": "PRODUCT_ID",
            "quantity": 1
        }
    ],
    "price_value": "344.33",
    "purchase_id": "ABC123"
});
```

{% endtab %}

{% tab title="Events" %}

```
pushly('purchase', {
    "events": [
        {
            "id": "EVENT_ID",
            "quantity": 1
        }
    ],
    "price_value": "344.33"
   "purchase_id": "ABC123"
});
```

{% endtab %}
{% endtabs %}

#### 購入フィールド

* **price\_value** – 購入総額。通貨はドメインに設定されたもの
* **purchase\_id** – 一意の注文識別子

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

#### 通貨の取り扱い

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

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

例:

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

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

* `id` はすべてのアイテムで必須です
* `quantity` は、カートまたは購入数量を追跡する場合にのみ必須です
* `rating` は、アイテムを評価する場合にのみ必須です
* 次のうち1つだけを `products`, `events`、または `recipes` 1回の呼び出しにつき含める必要があります

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

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

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

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

##