프로모션을 사용하면 판매자와 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 ...}
컴퓨팅 할인
프로모션 코드가 유효하면 처리에서 할인 금액을 계산하고 계산된 할인 금액이 포함된 CheckoutResponseMessage를 otherItems 배열로 다시 전송해야 합니다. 총 주문 가격은 음수여서는 안 됩니다. 할인 금액이 장바구니 금액을 초과하면 최대 금액을 다시 전송하여 총 주문 가격을 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의 프로모션 코드가 유효하지 않다고 판단되면 (예: 만료되었거나 잘못되었거나 인식되지 않음) 관련 오류 코드 및 이유 텍스트가 포함된 foodOrderError와 함께 correctedProposedOrder 및 paymentOptions 객체가 포함된 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." } ] } }