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

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

以下のイベントを送信する前に、Pushly iOS 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="Swift" %}

```swift
PushSDK.UserProfile.viewItem(item: CatalogItem(id: "ITEM_ID"))
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
CatalogItem *item = [[CatalogItem alloc] initWithId:@"ITEM_ID"];
[PushSDKUserProfile viewItemWithItem:item];
```

{% endtab %}
{% endtabs %}

### アイテムを保存

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

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

```swift
PushSDK.UserProfile.saveItem(item: CatalogItem(id: "ITEM_ID"))
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile saveItemWithItem:
    [[CatalogItem alloc] initWithId:@"ITEM_ID"]
];
```

{% endtab %}
{% endtabs %}

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

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

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

```swift
PushSDK.UserProfile.unsaveItem(
    item: CatalogItem(id: "ITEM_ID")
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile unsaveItemWithItem:
    [[CatalogItem alloc] initWithId:@"ITEM_ID"]
];
```

{% endtab %}
{% endtabs %}

### アイテムを完了

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

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

```swift
PushSDK.UserProfile.completeItem(
    item: CatalogItem(id: "ITEM_ID")
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile completeItemWithItem:
    [[CatalogItem alloc] initWithId:@"ITEM_ID"]
];
```

{% endtab %}
{% endtabs %}

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

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

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

```swift
PushSDK.UserProfile.uncompleteItem(
    item: CatalogItem(id: "ITEM_ID")
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile uncompleteItemWithItem:
    [[CatalogItem alloc] initWithId:@"ITEM_ID"]
];
```

{% endtab %}
{% endtabs %}

### アイテムを評価

この `rate_item` イベントには、任意の `rating` プロパティが含まれます。指定する場合、 `rating` は数値である必要があり、 **0 から 100 まで** の範囲内で、 **小数点以下 1 桁まで**.

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

```swift
PushSDK.UserProfile.rateItem(
    item: CatalogItem(id: "ITEM_ID", rating: 95)
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
CatalogItem *item = [[CatalogItem alloc] initWithId:@"ITEM_ID" rating:@95];
[PushSDKUserProfile rateItemWithItem:item];
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
この `rating` 値は製品のネイティブな尺度に合わせてください。ユースケースに適した範囲を使用してください（例: 星評価なら 1〜5、スコアなら 0〜10、パーセント形式の評価なら 1〜100）。唯一の要件は、その値が 0〜100 の範囲内で、小数点以下 1 桁を超えないことです。
{% endhint %}

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

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

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

```swift
PushSDK.UserProfile.unrateItem(
    item: CatalogItem(id: "ITEM_ID")
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile unrateItemWithItem:
    [[CatalogItem alloc] initWithId:@"ITEM_ID"]
];
```

{% endtab %}
{% endtabs %}

### カートに追加

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

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

```swift
PushSDK.UserProfile.addToCart(
    item: CatalogItem(id: "ITEM_ID", quantity: 2)
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile addToCartWithItem:
    [[CatalogItem alloc] initWithId:@"ITEM_ID" quantity:2]
];
```

{% endtab %}
{% endtabs %}

呼び出すことができます `add_to_cart` 必要な回数だけ、訪問者のカート内のすべてのアイテムを追跡してください。購入されていない、顧客のカート内の任意のアイテムに対して、カート放棄通知を送信できます。

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

### カートを更新

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

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

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

```swift
PushSDK.UserProfile.updateCart(withItems: [
    CatalogItem(id: "ITEM_1", quantity: 1),
    CatalogItem(id: "ITEM_2", quantity: 2)
])
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
NSArray *items = @[
    [[CatalogItem alloc] initWithId:@"ITEM_1" quantity:1],
    [[CatalogItem alloc] initWithId:@"ITEM_2" quantity:2]
];
[PushSDKUserProfile updateCartWithItems:items];
```

{% endtab %}
{% endtabs %}

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

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

```swift
PushSDK.UserProfile.updateCart(withItems: [])
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
[PushSDKUserProfile updateCartWithItems:@[]];
```

{% endtab %}
{% endtabs %}

### 購入

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

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

```swift
PushSDK.UserProfile.trackPurchase(
    of: [
        CatalogItem(id: "ITEM_1"),
        CatalogItem(id: "ITEM_2", quantity: 2)
    ],
    withPurchaseId: "ORDER_123",
    withPriceValue: "49.99"
)
```

{% endtab %}

{% tab title="Objective-C" %}

```objective-c
NSArray *items = @[
    [[CatalogItem alloc] initWithId:@"ITEM_1"],
    [[CatalogItem alloc] initWithId:@"ITEM_2" quantity:2]
];

[PushSDKUserProfile trackPurchaseWithItems:items
                      withPurchaseId:@"ORDER_123"
                     withPriceValue:@"49.99"];
```

{% endtab %}
{% endtabs %}

#### 購入フィールド

* **priceValue** – ドメインに設定された通貨での購入合計金額
* **purchaseId** – 一意の注文識別子

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

#### 通貨の取り扱い

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

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

例：

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

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

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

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

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

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

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