このページは Cloud Translation API によって翻訳されました。

プロモーション

プロモーションは、お客様と Google が割引料金で料理注文サービスをお試しいただけるようにするものです。Google は、注文と Google アクションをプロモーション管理システムに統合することをサポートしています。

次の種類の割引がサポートされています。

Google が出資するプロモーションコード: Google が自動的に事前入力するか、ユーザーが入力するプロモーションコード。
第三者提供のプロモーションコード: 料理注文サービスで提供される、ユーザーが入力するプロモーションコード。
サードパーティが提供する自動割引: 料理注文サービスがプロモーションコードなしで自動的に適用される割引。

割引の種類に関係なく、Google は料理を注文し、割引を確認して適用するために、フルフィルメントを注文します。

デリバリー&テイクアウトサービスを利用するデベロッパーは、実装を変更して、有効なプロモーションコードの割引の計算や無効なプロモーションコードのエラーの送信、プロモーションコードの利用制限の管理、払い戻しの会計データの追跡を行う必要があります。

プロモーションの処理方法

プロモーションをサポートするフルフィルメントを実装する手順は次のとおりです。

プロモーションの統合を設定します。（Google が支援するプロモーションコードを使用していない場合は、この手順をスキップしてください）。
プロモーションを使用して購入手続きを実装する。
プロモーションの注文を送信する

プロモーションの統合を設定する

このセクションでは、Google 提供のプロモーションコードを使用する場合に、プロモーションの統合を設定する方法について説明します。サードパーティのスポンサーによるプロモーションコードまたは割引のみをサポートする場合は、独自の設定を指定して、このセクションをスキップできます。

Google は、スポンサーに提供するプロモーションの種類を指定し、統合の設定についてパートナー様にご連絡します。以下で詳細をご確認ください。

割引額。
カートの最低額。
プロモーションコードの開始日と終了日。
プロモーションキャンペーンの予算額の上限。
プロモーションコードを利用できる回数。

プロモーションコードの例:

FopaNewUser: 10%（固定率）、最大 $50 オフ。
FopaMoreThan50: $10（固定額割引）

Google がコードの適用を中止する場合は、Google から連絡があります。

お支払いの設定

お支払いプロセスを設定するには、Google EAP コンサルタントにお問い合わせください。最終的な注文ステータスが次のいずれかである場合にのみ、Google が支援するプロモーションコードに関連する取引の払い戻しを行います。

CONFIRMED
IN_TRANSIT
READY_FOR_PICKUP
IN_PREPARATION
FULFILLED

プロモーションを使用して購入手続きを実装する

このセクションでは、プロモーションコード（Google が支援またはサードパーティが支援）をサポートする場合の決済処理の実装について説明します。サードパーティが提供する自動割引の場合、CheckoutResponseMessage の割引項目を返すだけで済みます（プロモーションコードの確認は必要ありません）。

料理の注文処理の際に、Google は CheckoutRequestMessage 内の単一のプロモーションコードをフルフィルメントに送信します。ユーザーは、購入手続きでリクエストが繰り返されたときにカートまたはプロモーションコードを変更できます。

ユーザーがプロモーションコードを初めて適用したかどうかを確認するには、次の手順を行います。

Google が出資するプロモーションコード: リピーターが同じプロモーションコードの使用を試みているかどうかを Google がチェックします。特に何もする必要はありません。
第三者提供のプロモーションコードまたは自動割引: アカウントのリンクとユーザーのオプトインを実装していない場合は、購入手続きのリクエストでユーザーの詳細を確認できません。代わりに、FoodCartExtension オブジェクトの Contact の詳細情報（ユーザーのメールアドレスなど）を使用して、SubmitOrderRequestMessage の処理中にこの状態を確認します。

最新の購入手続きリクエストに基づいて、フルフィルメントでエラーを特定するか、割引を計算します。その際は、ステイル状態の情報がシステムに保持されないようにしてください。

プロモーションコードの有効性を確認する

フルフィルメントは、有効期限、最大使用額、最大割引などの規定に照らして、特定のプロモーションコードの有効性または適格性をチェックする必要があります。次に、CheckoutResponseMessage で計算された割引を使用して適切に応答します。プロモーションコードを適用できない場合は foodOrderErrors を使用します。プロモーションコードでエラーが検出された場合は、プロモーションのエラーを処理するに記載されている手順に従ってください。

次のスニペットは、プロモーションコードの foodOrderErrors の例を示しています。correctedProposedOrder にプロモーションノードが含まれていないことを確認します。

"foodOrderErrors": [
  {
    "error": "PROMO_NOT_APPLICABLE",
    // Copy promotions.coupon string from CheckoutRequest as the ID
    "id": "GoogleNewUser",
    "description": "Promotion could not be applied"
  }
],
"correctedProposedOrder": {// required ...},
"paymentOptions": {// required ...}

コンピューティング割引

プロモーションコードが有効な場合は、フルフィルメントで割引額を計算し、計算された割引値を otherItems 配列にして CheckoutResponseMessage を返します。注文の合計金額は負数にできません。割引の金額がカートの金額を超える場合は、最大注文額を返すと、注文の合計金額が $0 になります。

次のスニペットは、プロモーション割引の CheckoutResponseMessage セクションの例を示しています。

"proposedOrder": {
   "otherItems": [
      . . .
      {
        "name": "Discount",
        // copy promotions.coupon field from CheckoutRequest as the id
        "id": "GoogleNewUser",
        "price": {
          "type": "ESTIMATE",
          "amount": {
          "currencyCode": "USD",
          "units": "-3",
          "nanos": -500000000
        }
      },
      "type": "DISCOUNT",
    }
  ]
}

未使用のプロモーションをリリースする

すべての購入手続きリクエストが注文送信リクエストにつながるわけではありません。購入手続き時にプロモーションが保留になった場合は、一定の期間が過ぎてからプロモーションの申請が行われなかった場合に、保留を解除する仕組みを用意してください。これにより、料理注文サービスで適切なキャンペーン割り当てを維持できます。

プロモーションに関するエラーの処理

CheckoutRequestMessage のプロモーションコードが有効でない（期限切れ、無効、認識できないなど）場合は、該当するエラーコードと理由テキスト、correctedProposedOrder、paymentOptions オブジェクトを含む foodOrderError で CheckoutResponseMessage を送信します。

フルフィルメントが同じリクエストからプロモーションコードエラーを複数検出した場合、回復可能なエラーを返す前に、回復不能エラーを送り返します。チェックの優先順位（優先順位: 高、低）:

PROMO_NOT_RECOGNIZED
PROMO_EXPIRED
PROMO_USER_INELIGIBLE
PROMO_ORDER_INELIGIBLE
PROMO_NOT_APPLICABLE

例

プロモーションコードを使った購入手続きリクエストの例を次に示します。

{
    "accessToken": "test_access_token",
    "lastSeen": "2018-06-22T19:25:39Z"
  },
  "conversation": {
    "conversationId": "XYZ"
  },
  "inputs": [
    {
      "intent": "actions.foodordering.intent.CHECKOUT",
      "arguments": [
        {
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.Cart",
            "merchant": {
              "id": "https://www.exampleprovider.com/merchant/id1",
              "name": "Falafel Bite"
            },
            "lineItems": [
              {
                "name": "Falafel Tray",
                "type": "REGULAR",
                "id": "sample_item_offer_id_1",
                "quantity": 1,
                "price": {
                  "type": "ESTIMATE",
                  "amount": {
                    "currencyCode": "USD",
                    "units": "9",
                    "nanos": 950000000
                  }
                },
                "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
                "extension": {
                  "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                }
              }
            ],
            "promotions": [
              {
                "coupon": "FOPAACTIVECODE"
              }
            ],
            "extension": {
              "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
              "fulfillmentPreference": {
                "fulfillmentInfo": {
                  "pickup": {
                    "pickupTimeIso8601": "P0M"
                  }
                }
              }
            }
          }
        }
      ]
    }
  ],
  "directActionOnly": true,
  "isInSandbox": true
}

プロモーションコードが有効な場合の、フルフィルメントからの対応する購入手続きレスポンスは次のとおりです。

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "structuredResponse": {
            "checkoutResponse": {
              "proposedOrder": {
                "otherItems": [
                  {
                    "name": "Delivery Fees",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "3",
                        "nanos": 500000000
                      }
                    },
                    "type": "DELIVERY"
                  },
                  {
                    "name": "Tax",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "1",
                        "nanos": 370000000
                      }
                    },
                    "type": "TAX"
                  },
                  {
                    "name": "Promotion",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "-5",
                        "nanos": 0
                      }
                    },
                    "id": "FOPAACTIVECODE",
                    "type": "DISCOUNT"
                  }
                ],
                "cart": {
                  "merchant": {
                    "id": "https://www.exampleprovider.com/merchant/id1",
                    "name": "Falafel Bite"
                  },
                  "lineItems": [
                    {
                      "name": "Falafel Tray",
                      "type": "REGULAR",
                      "id": "2529103",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "9",
                          "nanos": 950000000
                        }
                      },
                      "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                      }
                    }
                  ],
                  "promotions": [
                    {
                      "coupon": "FOPAACTIVECODE"
                    }
                  ],
                  "extension": {
                    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
                    "fulfillmentPreference": {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "P0M"
                        }
                      }
                    }
                  }
                },
                "totalPrice": {
                  "type": "ESTIMATE",
                  "amount": {
                    "currencyCode": "USD",
                    "units": "9",
                    "nanos": 820000000
                  }
                },
                "extension": {
                  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
                  "availableFulfillmentOptions": [
                    {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "P0M"
                        }
                      },
                      "expiresAt": "2018-06-22T19:30:52.596Z"
                    }
                  ]
                }
              },
              "orderOptions": {},
              "paymentOptions": {
                "googleProvidedOptions": {
                  "tokenizationParameters": {
                    "tokenizationType": "PAYMENT_GATEWAY",
                    "parameters": {
                      "gateway": "stripe",
                      "stripe:publishableKey": "example_stripe_client_key",
                      "stripe:version": "2017-04-06"
                    }
                  },
                  "supportedCardNetworks": [
                    "AMEX",
                    "DISCOVER",
                    "MASTERCARD",
                    "VISA",
                    "JCB"
                  ],
                  "prepaidCardDisallowed": true
                }
              }
            }
          }
        }
      ],
      "suggestions": []
    }
  }
}

プロモーションコードが無効な場合の購入手続きレスポンスの例を次に示します。

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "structuredResponse": {
            "error": {
              "foodOrderErrors": [
                {
                  "error": "PROMO_NOT_RECOGNIZED",
                  "id": "SOMEPROMO",
                  "description": "Coupon not found"
                }
              ],
              "correctedProposedOrder": {
                "cart": {
                  "merchant": {
                    "id": "https://www.exampleprovider.com/merchant/id1",
                    "name": "Falafel Bite"
                  },
                  "lineItems": [
                    {
                      "id": "sample_item_offer_id_4",
                      "name": "Prawns Biryani",
                      "type": "REGULAR",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "18",
                          "nanos": 750000000
                        }
                      },
                      "offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                      }
                    }
                  ],
                  "extension": {
                    "fulfillmentPreference": {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "P0M"
                        }
                      }
                    },
                    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension"
                  },
                  "promotions": []
                },
                "otherItems": [
                  {
                    "name": "Tax",
                    "type": "TAX",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "1",
                        "nanos": 650000000
                      }
                    }
                  }
                ],
                "termsOfServiceUrl": "https://exampleprovider.com/terms",
                "totalPrice": {
                  "type": "ESTIMATE",
                  "amount": {
                    "currencyCode": "USD",
                    "units": "20",
                    "nanos": 400000000
                  }
                },
                "extension": {
                  "availableFulfillmentOptions": [
                    {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "PT0M"
                        }
                      }
                    }
                  ],
                  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension"
                }
              },
              "paymentOptions": {
                "googleProvidedOptions": {
                  "prepaidCardDisallowed": false,
                  "billingAddressRequired": true,
                  "tokenizationParameters": {
                    "tokenizationType": "PAYMENT_GATEWAY",
                    "parameters": {
                      "gateway": "braintree",
                      "braintree:apiVersion": "v1",
                      "braintree:sdkVersion": "1.4.0",
                      "braintree:merchantId": "example_braintree_merchant_ID",
                      "braintree:clientKey": "example_braintree_client_key",
                      "braintree:authorizationFingerprint": "example_braintree_fingerprint"
                    }
                  }
                }
              },
              "@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension"
            }
          }
        }
      ]
    }
  }
}

プロモーションで注文を送信する

注文のフルフィルメントで、ユーザーがプロモーションコードを初めて適用したかどうかを確認します。SubmitOrderRequestMessage の処理中に、FoodCartExtension オブジェクトの Contact の詳細（ユーザーのメールアドレスなど）を使用して、この処理を確認できます。

また、プロモーションコードの適用対象も再度ご確認ください。

コードが適用される場合: 注文を確認し、クーポンを利用済みとしてマークします。
コードが適用できなくなった場合: PROMO_NOT_APPLICABLE エラーで注文を拒否します。FoodOrderUpdateExtension と同じメカニズムを使用して、具体的な不承認の理由を指定できます。

例

プロモーションを使用した注文送信リクエストの例を次に示します。

{
  "conversation": {
    "conversationId": "example_conversation_ID"
  },
  "inputs": [
    {
      "intent": "actions.intent.TRANSACTION_DECISION",
      "arguments": [
        {
          "transactionDecisionValue": {
            "order": {
              "finalOrder": {
                "cart": {
                  "merchant": {
                    "id": "https://www.exampleprovider.com/merchant/id1",
                    "name": "Falafel Bite"
                  },
                  "lineItems": [
                    {
                      "name": "Falafel Tray",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_1",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "9",
                          "nanos": 950000000
                        }
                      },
                      "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                      }
                    }
                  ],
                  "promotions": [
                    {
                      "coupon": "FOPAACTIVECODE"
                    }
                  ],
                  "extension": {
                    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
                    "fulfillmentPreference": {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "P0M"
                        }
                      }
                    },
                    "contact": {
                      "displayName": "Food Ordering",
                      "email": "example.provider@gmail.com",
                      "phoneNumber": "+19993334444",
                      "firstName": "Food",
                      "lastName": "Ordering"
                    }
                  }
                },
                "otherItems": [
                  {
                    "name": "Delivery Fees",
                    "type": "DELIVERY",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "3",
                        "nanos": 500000000
                      }
                    }
                  },
                  {
                    "name": "Tax",
                    "type": "TAX",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "1",
                        "nanos": 370000000
                      }
                    }
                  },
                  {
                    "name": "Promotion",
                    "type": "DISCOUNT",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "-5"
                      }
                    },
                    "id": "FOPAACTIVECODE"
                  },
                  {
                    "name": "Subtotal",
                    "type": "SUBTOTAL",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "9",
                        "nanos": 950000000
                      }
                    }
                  },
                  {
                    "name": "Tip",
                    "type": "GRATUITY",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD"
                      }
                    }
                  }
                ],
                "totalPrice": {
                  "type": "ESTIMATE",
                  "amount": {
                    "currencyCode": "USD",
                    "units": "9",
                    "nanos": 820000000
                  }
                },
                "extension": {
                  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension"
                }
              },
              "googleOrderId": "example_google_order_ID",
              "orderDate": "2018-06-22T19:30:59.502Z",
              "paymentInfo": {
                "displayName": "example_display_name",
                "googleProvidedPaymentInstrument": {
                  "instrumentToken": "example_instrument_token"
                },
                "paymentType": "PAYMENT_CARD"
              },
              "locale": "en"
            }
          }
        }
      ]
    }
  ],
  "directActionOnly": true,
  "isInSandbox": true
}

プロモーションコードが有効な場合、フルフィルメントから対応する注文送信レスポンスの例を次に示します。

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "structuredResponse": {
            "orderUpdate": {
              "actionOrderId": "example_action_order_ID",
              "orderState": {
                "state": "CREATED",
                "label": "Order is created with partner."
              },
              "updateTime": "2018-06-22T19:31:01.556Z",
              "orderManagementActions": [
                {
                  "type": "CALL_RESTAURANT",
                  "button": {
                    "title": "Call Us",
                    "openUrlAction": {
                      "url": "tel:+1-111-111-1111"
                    }
                  }
                },
                {
                  "type": "EMAIL",
                  "button": {
                    "title": "Email Us",
                    "openUrlAction": {
                      "url": "mailto:example.provider@gmail.com"
                    }
                  }
                },
                {
                  "type": "CUSTOMER_SERVICE",
                  "button": {
                    "title": "Customer Service",
                    "openUrlAction": {
                      "url": "http://www.google.com"
                    }
                  }
                }
              ]
            }
          }
        }
      ],
      "suggestions": []
    }
  }
}

プロモーションコードが無効な場合の注文送信レスポンスの例を次に示します。

"orderUpdate": {
  "actionOrderId": "sample_action_order_id",
  "orderState": {
    "state": "REJECTED",
    "label": "Order rejected."
  },
  "updateTime": "2017-05-10T02:30:00.000Z",
  "rejectionInfo": {
    "type": "PROMO_NOT_APPLICABLE",
    "reason": "Sorry, there's something wrong. Try another code?"
  },
  "orderManagementActions": [
    {
      "type": "CUSTOMER_SERVICE",
      "button": {
        "title": "Contact customer service",
        "openUrlAction": {
          "url": "mailto:support@example.com"
        }
      }
    },
    {
      "type": "EMAIL",
      "button": {
        "title": "Email restaurant",
        "openUrlAction": {
          "url": "mailto:example.provider@example.com"
        }
      }
    },
    {
      "type": "CALL_RESTAURANT",
      "button": {
        "title": "Call restaurant",
        "openUrlAction": {
          "url": "tel:+19993334444"
        }
      }
    }
  ],
  "infoExtension": {
    "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
    "foodOrderErrors": [
      {
        "error": "PROMO_USER_INELIGIBLE",
        "description": "Sorry, you can only use this promotion once."
      }
    ]
  }
}