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

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

以下で説明するイベントを送信する前に、Pushly React Native 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** – ユーザーが取引を完了する

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

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

### アイテム閲覧

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

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

```typescript
PushSDK.UserProfile.viewItem({ id: 'ITEM_ID' })
```

{% endtab %}
{% endtabs %}

### アイテム保存

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

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

```typescript
PushSDK.UserProfile.saveItem({ id: 'ITEM_ID' })
```

{% endtab %}
{% endtabs %}

### アイテム保存解除

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

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

```typescript
PushSDK.UserProfile.unsaveItem({ id: 'ITEM_ID' })
```

{% endtab %}
{% endtabs %}

### アイテム完了

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

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

```typescript
PushSDK.UserProfile.completeItem({ id: 'ITEM_ID' })
```

{% endtab %}
{% endtabs %}

### アイテム完了解除

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

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

```typescript
PushSDK.UserProfile.uncompleteItem({ id: 'ITEM_ID' })
```

{% endtab %}
{% endtabs %}

### アイテム評価

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

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

```typescript
PushSDK.UserProfile.rateItem({ id: 'ITEM_ID', rating: 5 })
```

{% endtab %}
{% endtabs %}

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

### アイテム評価解除

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

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

```typescript
PushSDK.UserProfile.unrateItem({ id: 'ITEM_ID' })
```

{% endtab %}
{% endtabs %}

### カートに追加

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

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

```typescript
PushSDK.UserProfile.addToCart([{ id: 'ITEM_ID', quantity: 5 }])
```

{% endtab %}
{% endtabs %}

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

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

### カート更新

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

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

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

```typescript
PushSDK.UserProfile.updateCart([{ id: 'ITEM_ID', quantity: 7 }])
```

{% endtab %}
{% endtabs %}

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

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

```typescript
PushSDK.UserProfile.updateCart([])
```

{% endtab %}
{% endtabs %}

### 購入

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

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

```typescript
PushSDK.UserProfile.trackPurchase(
    [{ id: 'ITEM_ID', quantity: 5 }], // items
    "ABC123",                         // purchase_id
    "344.33"                          // 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` イベントは、誤ったカゴ落ち通知を避けるため、可能な限り信頼できる確認ステップから発火させてください。