プロモーションは、販売者と Google が、ユーザーに割引料金で料理注文サービスを試すよう促すことができます。Google では、注文に関するエンドツーエンドのアクションをプロモーション管理システムに統合できます。
次のタイプの割引がサポートされています。
- Google 提供のプロモーション コード: Google によって自動的に入力される、またはユーザーが入力するプロモーション コード。
- サードパーティ提供のプロモーション コード: ユーザーが入力できるプロモーション コード。フード注文サービスから提供されます。
- サードパーティ提供の自動割引: プロモーション コードなしで料理注文サービスが自動的に適用される割引。
割引の種類に関係なく、Google は食品注文フルフィルメントに対して購入手続きを呼び出し、割引を確認して適用します。
料理注文サービスのデベロッパーは、有効なプロモーション コードの割引の計算、無効なプロモーション コードのエラーの送信、プロモーション コードの利用制限の管理、返金用の会計データの追跡を行うために、実装に変更を加える必要があります。
プロモーションを処理する方法
プロモーションをサポートするフルフィルメントを実装する手順は次のとおりです。
- プロモーションの統合を設定する（Google 提供のプロモーション コードを使用しない場合は、この手順をスキップしてください）。
- プロモーションを使用して購入手続きを実装する。
- プロモーション付きの注文送信を実装します。
プロモーションの統合を設定する
このセクションでは、Google 提供のプロモーション コードを使用する場合にプロモーションの統合を設定する方法について説明します。サードパーティが提供するプロモーション コードや割引のみをサポートする場合は、独自の設定を指定して、このセクションをスキップできます。
Google はスポンサーになるプロモーションのタイプを指定し、統合を設定するようデベロッパーに連絡します。次の情報が提供されます。
- 割引額。
- カートの最低額。
- プロモーション コードを使用する開始日と終了日。
- プロモーション キャンペーンの予算の上限額。
- プロモーション コードを使用できる回数。
プロモーション コードの例:
FopaNewUser: 10%（固定パーセント）、最大 50 ドル割引。FopaMoreThan50: 10 ドル（固定額割引）。
コードの適用を中止する場合は、Google から通知が届きます。
支払いを設定する
Google EAP コンサルタントに連絡して、支払いプロセスを設定します。 最終的な注文ステータスが次のいずれかである場合にのみ、Google 提供のプロモーション コードに関連する取引のみが Google で払い戻されます。
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
プロモーションを使用した購入手続きを実装する
このセクションでは、プロモーション コード（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_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_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."
}
]
}
}