# コマースおよびカタログアイテムイベント このガイドでは、Android SDK を使用して、コマースおよびカタログ関連のユーザー操作を Pushly に送信する方法について説明します。これらのイベントは、カート放棄通知、保存済みアイテムのリマインダー、収益アトリビューション、カタログ駆動型レコメンデーションキャンペーンなどの機能を支えます。 以下のイベントを送信する前に、Pushly Android 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="Kotlin" %} ```kotlin PushSDK.UserProfile.viewItem(CatalogItem(id = "ITEM_ID")) ``` {% endtab %} {% tab title="Java" %} ```java PushSDK.UserProfile.viewItem(new CatalogItem("ITEM_ID")); ``` {% endtab %} {% endtabs %} ### アイテムを保存 ユーザーがアイテムを保存、お気に入り登録、またはブックマークしたときにこのイベントを使用します。これにより、保存済みアイテムのリマインダーキャンペーンを有効にできます。 {% tabs %} {% tab title="Kotlin" %} ```kotlin PushSDK.UserProfile.saveItem(CatalogItem(id = "ITEM_ID")) ``` {% endtab %} {% tab title="Java" %} ```java PushSDK.UserProfile.saveItem(new CatalogItem("ITEM_ID")); ``` {% endtab %} {% endtabs %} ### 保存解除アイテム ユーザーがアイテムを保存済みリスト、お気に入り、またはブックマークから削除したときにこのイベントを使用します。 {% tabs %} {% tab title="Kotlin" %} ```kotlin PushSDK.UserProfile.unsaveItem(CatalogItem(id = "ITEM_ID")) ``` {% endtab %} {% tab title="Java" %} ```java PushSDK.UserProfile.unsaveItem(new CatalogItem("ITEM_ID")); ``` {% endtab %} {% endtabs %} ### アイテムを完了 ユーザーが意図された体験を完了した後に、アイテムを完了済みとしてマークします。 {% tabs %} {% tab title="Kotlin" %} ```kotlin PushSDK.UserProfile.completeItem(CatalogItem(id = "ITEM_ID")) ``` {% endtab %} {% tab title="Java" %} ```java PushSDK.UserProfile.completeItem(new CatalogItem("ITEM_ID")); ``` {% endtab %} {% endtabs %} ### アイテムの完了を解除 アイテムの完了状態を元に戻すには、このイベントを使用します。 {% tabs %} {% tab title="Kotlin" %} ```kotlin PushSDK.UserProfile.uncompleteItem(CatalogItem(id = "ITEM_ID")) ``` {% endtab %} {% tab title="Java" %} ```java PushSDK.UserProfile.uncompleteItem(new CatalogItem("ITEM_ID")); ``` {% endtab %} {% endtabs %} ### アイテムを評価 この `rate_item` イベントには、任意の `rating` プロパティが含まれます。指定する場合、 `rating` は次の範囲の数値である必要があります **0 から 100 まで** の範囲内で、 **小数点以下 1 桁まで**です。整数値も有効です。 {% tabs %} {% tab title="Kotlin" %} ```kotlin PushSDK.UserProfile.rateItem(CatalogItem(id = "ITEM_ID", rating = 5)) ``` {% endtab %} {% tab title="Java" %} ```java PushSDK.UserProfile.rateItem(new CatalogItem("ITEM_ID")); ``` {% endtab %} {% endtabs %} {% hint style="info" %} この `rating` 値は製品本来のスケールに合わせてください。用途に合う任意の範囲を使用できます（例: 星評価なら 1～5、スコアなら 0～10、割合形式の評価なら 1～100）。唯一の要件は、その値が 0～100 の範囲内であり、小数点以下 1 桁を超えないことです。 {% endhint %} ### アイテムの評価を解除 ユーザーがアイテムの評価を削除したときにこのイベントを使用します。 {% tabs %} {% tab title="Kotlin" %} ```kotlin PushSDK.UserProfile.unrateItem(CatalogItem(id = "ITEM_ID")) ``` {% endtab %} {% tab title="Java" %} ```java PushSDK.UserProfile.unrateItem(new CatalogItem("ITEM_ID")); ``` {% endtab %} {% endtabs %} ### カートに追加 ユーザーがアイテムをカートに追加したら、その都度このイベントを送信します。Pushly は複数回の呼び出しにわたってカート状態を累積します。 {% tabs %} {% tab title="Kotlin" %} ```kotlin PushSDK.UserProfile.addToCart(listOf(CatalogItem("ITEM_ID", 5))) ``` {% endtab %} {% tab title="Java" %} ```java List items = new ArrayList<>(); items.add(new CatalogItem("ITEM_ID", 5)); PushSDK.UserProfile.addToCart(items); ``` {% endtab %} {% endtabs %} 必要に応じて `add_to_cart` を何度でも呼び出し、訪問者のカート内のすべてのアイテムを追跡できます。購入されていない顧客のカート内アイテムについては、カート放棄通知が送信される場合があります。 購入が行われると、訪問者のカートは空になり、購入済みアイテムに関する通知は訪問者に送信されません。 ### カートを更新 ユーザーが購入を完了せずにカートを変更した場合、たとえば数量を調整したりアイテムを削除したりした場合に、このイベントを使用します。 カートからアイテムを削除するには、 `update_cart` メソッドに現在のカート全体の情報を渡します（削除したアイテムは含めません）。 {% tabs %} {% tab title="Kotlin" %} ```kotlin PushSDK.UserProfile.updateCart(listOf(CatalogItem("ITEM_ID", 5))) ``` {% endtab %} {% tab title="Java" %} ```java List items = new ArrayList<>(); items.add(new CatalogItem("ITEM_ID", 5)); PushSDK.UserProfile.updateCart(items); ``` {% endtab %} {% endtabs %} また、カートが完全に空になった場合は、空の配列を指定します。 {% tabs %} {% tab title="Kotlin" %} ```kotlin PushSDK.EComm.updateCart(emptyList()) ``` {% endtab %} {% tab title="Java" %} ```java PushSDK.EComm.updateCart(new ArrayList<>()); ``` {% endtab %} {% endtabs %} ### 購入 チェックアウトが成功した後にこのイベントを送信します。これによりカート放棄状態がクリアされ、収益アトリビューションが有効になります。 {% tabs %} {% tab title="Kotlin" %} ```kotlin PushSDK.UserProfile.trackPurchase( items = listOf(CatalogItem(id = "ITEM_ID", quantity = 5)), purchaseId = "ABC123", priceValue = "344.33" ) ``` {% endtab %} {% tab title="Java" %} ```java List items = new ArrayList<>(); items.add(new CatalogItem("ITEM_ID", 5)); PushSDK.UserProfile.trackPurchase(items, "ABC123", "344.33"); ``` {% endtab %} {% endtabs %} #### 購入フィールド * **priceValue** – 購入総額。ドメインに設定された通貨で指定します * **purchaseId** – 一意の注文識別子 もし `purchase` イベントがアイテムデータなしで送信された場合でも、Pushly はユーザーのカート状態をクリアします。 #### 通貨の扱い `price_value` は、プラットフォームのドメイン設定でドメインに対して構成された通貨で指定する必要があります。 小数点記号にはピリオド（`.`）を使用してください。ロケールに関係なく、すべての通貨でピリオドを使用します。カンマは使用しないでください。 例: * USD: `"344.33"` * JPY: `"5000"` ### 必須フィールドの概要 * `id` はすべてのアイテムで必須です * `quantity` は、カート数量または購入数量を追跡する場合にのみ必須です * `rating` は、アイテムを評価する場合にのみ必須です ### 実装のベストプラクティス イベントの取りこぼしを防ぐため、SDK はページライフサイクルの早い段階で初期化してください。 すべてのインタラクションタイプで一貫したアイテム ID を使用し、Pushly が行動を正しく関連付けられるようにしてください。 トリガー `purchase` 偽のカート放棄通知を避けるため、可能な限り信頼できる確認ステップからイベントを送信してください。