Ta strona została przetłumaczona przez Cloud Translation API.

Tworzenie transakcji fizycznych w Google Pay

Ten przewodnik przedstawia proces opracowywania projektu w Actions, który obejmuje transakcje sprzedaży towarów fizycznych i korzystanie z Google Pay do płatności.

Przepływ transakcji

Gdy Twój projekt Actions obsługuje transakcje fizyczne za pomocą płatności zarządzanych przez sprzedawcę, używa tego przepływu:

Gromadzenie informacji (opcjonalnie) – w zależności od charakteru transakcji możesz od razu rozpocząć rozmowę z następującymi informacjami:
1. Sprawdź wymagania dotyczące transakcji – na początku rozmowy sprawdź, czy użytkownik spełnia wymagania dotyczące transakcji, np. prawidłowo skonfigurował i udostępnił dane karty przed utworzeniem koszyka.
2. Żądanie adresu dostawy – jeśli transakcja wymaga adresu dostawy, zbierz ten adres od użytkownika.
Utwórz zamówienie – zaprezentuj użytkownikowi, jak „złożyć koszyk”, w którym wybiera produkty, które chce kupić.
Zaproponuj zamówienie – gdy koszyk będzie gotowy, zaproponuj zamówienie użytkownikowi, by mógł potwierdzić, że jest prawidłowy. Jeśli zamówienie zostanie potwierdzone, otrzymasz odpowiedź ze szczegółami zamówienia i tokenem płatności.
Sfinalizować zamówienie i wysłać potwierdzenie – po potwierdzeniu zamówienia zaktualizuj śledzenie zasobów reklamowych lub inne usługi realizacji zamówień, a potem wyślij potwierdzenie do użytkownika.
Wysyłanie aktualizacji zamówień – w trakcie okresu realizacji zamówienia przekazuj aktualizacje zamówień użytkownika, wysyłając żądania PATCH do interfejsu Orders API.

Ograniczenia i wytyczne dotyczące sprawdzania

Pamiętaj, że w przypadku akcji z transakcjami obowiązują dodatkowe zasady. Sprawdzenie działań w transakcjach może potrwać do 6 tygodni, dlatego uwzględnij ten czas podczas planowania harmonogramu publikacji. Aby ułatwić proces sprawdzania, przed przesłaniem akcji do sprawdzenia upewnij się, że przestrzegasz zasad i wytycznych dotyczących transakcji.

Działania, które prowadzą sprzedaż towarów fizycznych, możesz wdrożyć tylko w tych krajach:

Australia
Brazylia
Kanada
Indonezja

Japonia
Meksyk
Rosja

Singapur
Tajlandia
Turcja
Wielka Brytania
Stany Zjednoczone

Tworzenie projektu

Pełne przykłady rozmów o transakcjach znajdziesz w przykładzie transakcji w Node.js.

Konfiguracja

Podczas tworzenia działania musisz za pomocą Konsoli Actions wskazać, że chcesz wykonywać transakcje.

Aby skonfigurować projekt i realizację, wykonaj te czynności:

Utwórz nowy projekt lub zaimportuj istniejący.
Kliknij Wdróż > Informacje o katalogu.
W sekcji Dodatkowe informacje > Transakcje zaznacz pole „Czy Twoje działania korzystają z interfejsu API transakcji do przeprowadzania transakcji towarów fizycznych?”.

1. Zbierz informacje (opcjonalnie)

1a. Sprawdź wymagania dotyczące transakcji (opcjonalnie)

Gdy tylko użytkownik potwierdzi, że chce dokonać zakupu, sprawdź, czy może on dokonać transakcji. Po wywołaniu, działanie może na przykład zapytać: „Czy chcesz zamówić buty, czy sprawdzić saldo konta?”. Jeśli użytkownik powie „zamów buty”, sprawdź, czy można kontynuować, i umożliwi mu to rozwiązanie problemu. Aby to zrobić, przejdź do sceny, która sprawdza wymagania dotyczące transakcji.

Utwórz scenę kontroli wymagań dotyczących transakcji

Na karcie Sceny dodaj nową scenę o nazwie TransactionRequirementsCheck.
W sekcji Wypełnienie boksu kliknij +, by dodać nowy boks.
W sekcji Wybierz typ wybierz actions.type.TransactionRequirementsCheckResult jako typ boksu.
W polu nazwy boksu wpisz nazwę TransactionRequirementsCheck.
Zaznacz pole wyboru Dostosuj odpowiedź do wartości boksu (domyślnie włączone).
Kliknij Zapisz.

Sprawdzenie wymagań dotyczących transakcji spowoduje jeden z tych wyników:

Jeśli są spełnione wymagania, parametr sesji jest objęty warunkiem powodzenia i możesz kontynuować tworzenie zamówienia użytkownika.
Jeśli nie można spełnić co najmniej jednego z tych wymagań, parametr sesji jest ustawiany jako warunek niepowodzenia. W takim przypadku musisz odwrócić rozmowę o transakcji lub ją zakończyć.
- Jeśli użytkownik naprawi błędy, które powodują wystąpienie błędu, może on rozwiązać dany problem na urządzeniu. Jeśli rozmowa odbywa się tylko na powierzchni głosu, do telefonu użytkownika zostanie przekierowany użytkownik.

Wynik kontroli wymagań dotyczących transakcji

Na karcie Sceny wybierz nowo utworzoną scenę TransactionRequirementsCheck.
W sekcji Warunek kliknij +, by dodać nowy warunek.

W polu tekstowym wpisz poniższą składnię warunku, by sprawdzić stan powodzenia:

scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"

Najedź kursorem na nowo dodany warunek i kliknij strzałkę w górę, aby umieścić go przed if scene.slots.status == "FINAL".

Włącz Wyślij potwierdzenia i uzyskaj proste powiadomienie o gotowości do dokonania transakcji:

candidates:
  - first_simple:
      variants:
        - speech: >-
            You are ready to purchase physical goods.

W sekcji Przejście wybierz inną scenę, aby użytkownik mógł kontynuować rozmowę i kontynuować transakcję.
Wybierz warunek else if scene.slots.status == "FINAL".
Włącz Wyślij potwierdzenia i uzyskaj proste powiadomienie z informacją, że klient nie może dokonać transakcji:
```
candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.
```
W sekcji Przejście wybierz Zakończ rozmowę, jeśli użytkownik nie może przeprowadzać transakcji.

Poproś o adres dostawy

Jeśli transakcja wymaga użycia adresu dostawy użytkownika, musisz zażądać tego adresu od użytkownika. Może to być przydatne przy określaniu łącznej ceny, lokalizacji dostawy lub odbioru albo by upewnić się, że użytkownik znajduje się w regionie świadczenia usługi. Aby to zrobić, przejdź na scenę, w której użytkownik otrzymuje adres dostawy.

Utwórz scenę w adresie dostawy

Na karcie Sceny dodaj nową scenę o nazwie DeliveryAddress.
W sekcji Wypełnienie boksu kliknij +, by dodać nowy boks.
W sekcji Wybierz typ wybierz actions.type.DeliveryAddressValue jako typ boksu.
W polu nazwy boksu wpisz nazwę TransactionDeliveryAddress.
Zaznacz pole wyboru Dostosuj odpowiedź do wartości boksu (domyślnie włączone).
Kliknij Zapisz.

Podczas konfigurowania boksu możesz podać reason, aby móc wysłać użytkownikowi żądanie prośby o uzyskanie adresu za pomocą ciągu znaków.Domyślnym ciągiem znaków jest „wiedzie, gdzie wysłać zamówienie”. Asystent może więc zapytać użytkownika: „Aby wiedzieć, gdzie wysłać zamówienie, muszę poznać Twój adres dostawy”.

Na platformach z ekranem użytkownik wybiera adres, którego chce użyć przy transakcji. Jeśli wcześniej nie podał adresu, będzie mógł wpisać nowy adres.
Na platformach obsługujących tylko funkcję Voice Asystent użytkownik poprosi użytkownika o pozwolenie na udostępnienie domyślnego adresu transakcji. Jeśli użytkownik nie podał wcześniej adresu, rozmowa zostanie przekazana na telefon w celu dołączenia do rozmowy.

Aby przetworzyć adres dostawy:

Na karcie Sceny wybierz nowo utworzoną scenę DeliveryAddress.
W sekcji Warunek kliknij +, by dodać nowy warunek.

W polu tekstowym wpisz poniższą składnię warunku, by sprawdzić stan powodzenia:

scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"

Najedź kursorem na nowo dodany warunek i kliknij strzałkę w górę, aby umieścić go przed if scene.slots.status == "FINAL".

Włącz Wyślij potwierdzenia i zamieść proste powiadomienie o otrzymaniu adresu przez użytkownika:

candidates:
  - first_simple:
      variants:
        - speech: >-
            Great! Your order will be delivered to
            $session.params.TransactionDeliveryAddress.location.postalAddress.locality
            $session.params.TransactionDeliveryAddress.location.postalAddress.administrativeArea
            $session.params.TransactionDeliveryAddress.location.postalAddress.regionCode
            $session.params.TransactionDeliveryAddress.location.postalAddress.postalCode

W sekcji Przejście wybierz inną scenę, aby użytkownik mógł kontynuować rozmowę.
Wybierz warunek else if scene.slots.status == "FINAL".
Włącz Wyślij potwierdzenia i uzyskaj proste powiadomienie z informacją, że klient nie może dokonać transakcji:
```
candidates:
  - first_simple:
      variants:
        - speech: I failed to get your delivery address.
```
W sekcji Przejście wybierz Zakończ rozmowę, jeśli użytkownik nie może przeprowadzać transakcji.

Utwórz zamówienie

Gdy zbierzesz potrzebne informacje o użytkownikach, stworzysz interfejs do składania koszyka, który pozwoli użytkownikowi utworzyć zamówienie. Każda akcja będzie wyglądać nieco inaczej niż w przypadku konkretnego produktu lub usługi.

Najprostszy sposób tworzenia koszyków polega na tym, że użytkownik wybiera elementy z listy, aby dodać je do zamówienia. Możesz jednak zaprojektować rozmowę tak, aby uprościć korzystanie z witryny. Możesz stworzyć interfejs funkcji koszyka na zakupy, który pozwoli użytkownikom na zmianę kolejności ostatnich zakupów, zadając proste pytanie „tak” lub „nie”. Możesz też wyświetlić użytkownikowi karuzelę lub kartę z najważniejszymi elementami, które są polecane lub polecane.

Zalecamy korzystanie z bogatych odpowiedzi w celu prezentowania opcji użytkownika, a także zaprojektowanie wątku tak, aby użytkownik mógł utworzyć koszyk, używając tylko swojego głosu. Sprawdzone metody i przykłady wysokiej jakości koszyków znajdziesz w wytycznych dotyczących projektowania.

Tworzenie zamówienia

Podczas rozmowy musisz zebrać elementy, które użytkownik chce kupić, a potem utworzyć obiekt Order.

Order musi zawierać przynajmniej:

buyerInfo – informacje o użytkowniku, który dokonał zakupu.
transactionMerchant – informacje o sprzedawcy, który ułatwił zamówienie.
contents – rzeczywista zawartość zamówienia podana jako lineItems.
priceAttributes – szczegóły ceny zamówienia, w tym całkowity koszt zamówienia ze zniżkami i podatkami.

Zapoznaj się z dokumentacją odpowiedzi na Order, aby utworzyć koszyk. Pamiętaj, że w zależności od kolejności może być konieczne dodanie różnych pól.

Przykładowy kod poniżej pokazuje pełne zamówienie wraz z polami opcjonalnymi:

const order = {
  createTime: '2019-09-24T18:00:00.877Z',
  lastUpdateTime: '2019-09-24T18:00:00.877Z',
  merchantOrderId: orderId, // A unique ID String for the order
  userVisibleOrderId: orderId,
  transactionMerchant: {
    id: 'http://www.example.com',
    name: 'Example Merchant',
  },
  contents: {
    lineItems: [
      {
        id: 'LINE_ITEM_ID',
        name: 'Pizza',
        description: 'A four cheese pizza.',
        priceAttributes: [
          {
            type: 'REGULAR',
            name: 'Item Price',
            state: 'ACTUAL',
            amount: {
              currencyCode: 'USD',
              amountInMicros: 8990000,
            },
            taxIncluded: true,
          },
          {
            type: 'TOTAL',
            name: 'Total Price',
            state: 'ACTUAL',
            amount: {
              currencyCode: 'USD',
              amountInMicros: 9990000,
            },
            taxIncluded: true,
          },
        ],
        notes: [
          'Extra cheese.',
        ],
        purchase: {
          quantity: 1,
          unitMeasure: {
            measure: 1,
            unit: 'POUND',
          },
          itemOptions: [
            {
              id: 'ITEM_OPTION_ID',
              name: 'Pepperoni',
              prices: [
                {
                  type: 'REGULAR',
                  state: 'ACTUAL',
                  name: 'Item Price',
                  amount: {
                    currencyCode: 'USD',
                    amountInMicros: 1000000,
                  },
                  taxIncluded: true,
                },
                {
                  type: 'TOTAL',
                  name: 'Total Price',
                  state: 'ACTUAL',
                  amount: {
                    currencyCode: 'USD',
                    amountInMicros: 1000000,
                  },
                  taxIncluded: true,
                },
              ],
              note: 'Extra pepperoni',
              quantity: 1,
              subOptions: [],
            },
          ],
        },
      },
    ],
  },
  buyerInfo: {
    email: 'janedoe@gmail.com',
    firstName: 'Jane',
    lastName: 'Doe',
    displayName: 'Jane Doe',
  },
  priceAttributes: [
    {
      type: 'SUBTOTAL',
      name: 'Subtotal',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 9990000,
      },
      taxIncluded: true,
    },
    {
      type: 'DELIVERY',
      name: 'Delivery',
      state: 'ACTUAL',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 2000000,
      },
      taxIncluded: true,
    },
    {
      type: 'TAX',
      name: 'Tax',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 3780000,
      },
      taxIncluded: true,
    },
    {
      type: 'TOTAL',
      name: 'Total Price',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 15770000,
      },
      taxIncluded: true,
    },
  ],
  followUpActions: [
    {
      type: 'VIEW_DETAILS',
      title: 'View details',
      openUrlAction: {
        url: 'http://example.com',
      },
    },
    {
      type: 'CALL',
      title: 'Call us',
      openUrlAction: {
        url: 'tel:+16501112222',
      },
    },
    {
      type: 'EMAIL',
      title: 'Email us',
      openUrlAction: {
        url: 'mailto:person@example.com',
      },
    },
  ],
  termsOfServiceUrl: 'http://www.example.com',
  note: 'Sale event',
  promotions: [
    {
      coupon: 'COUPON_CODE',
    },
  ],
  purchase: {
    status: 'CREATED',
    userVisibleStatusLabel: 'CREATED',
    type: 'FOOD',
    returnsInfo: {
      isReturnable: false,
      daysToReturn: 1,
      policyUrl: 'http://www.example.com',
    },
    fulfillmentInfo: {
      id: 'FULFILLMENT_SERVICE_ID',
      fulfillmentType: 'DELIVERY',
      expectedFulfillmentTime: {
        timeIso8601: '2019-09-25T18:00:00.877Z',
      },
      location: location,
      price: {
        type: 'REGULAR',
        name: 'Delivery Price',
        state: 'ACTUAL',
        amount: {
          currencyCode: 'USD',
          amountInMicros: 2000000,
        },
        taxIncluded: true,
      },
      fulfillmentContact: {
        email: 'johnjohnson@gmail.com',
        firstName: 'John',
        lastName: 'Johnson',
        displayName: 'John Johnson',
      },
    },
    purchaseLocationType: 'ONLINE_PURCHASE',
  },
};

Opcje tworzenia zamówień i prezentacji

Zanim użytkownik potwierdzi swoje zamówienie, zobaczy proponowaną kartę zamówienia. Możesz dostosować sposób wyświetlania tej karty użytkownikowi, ustawiając różne opcje kolejności i prezentacji.

Poniżej znajdziesz opcje składania zamówień i prezentacji, które umożliwiają złożenie zamówienia, który wymaga podania adresu dostawy, w tym adresu e-mail użytkownika na karcie potwierdzenia zamówienia:

const orderOptions = {
      'requestDeliveryAddress': true,
      'userInfoOptions': {
        'userInfoProperties': ['EMAIL']
      }
    };

const presentationOptions = {
      'actionDisplayName': 'PLACE_ORDER'
    };

Utwórz parametry płatności

Twój obiekt paymentParameters będzie zawierał parametry tokenizacji, które zmieniają się w zależności od dostawcy procesora Google Pay, którego zamierzasz użyć (np. Stripe, Braintree, ACI itp.).

const paymentParamenters = {
      'googlePaymentOption': {
        // facilitationSpec is expected to be a serialized JSON string
        'facilitationSpec': JSON.stringify({
          'apiVersion': 2,
          'apiVersionMinor': 0,
          'merchantInfo': {
            'merchantName': 'Example Merchant',
          },
          'allowedPaymentMethods': [
            {
              'type': 'CARD',
              'parameters': {
                'allowedAuthMethods': ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
                'allowedCardNetworks': [
                  'AMEX', 'DISCOVER', 'JCB', 'MASTERCARD', 'VISA'],
              },
              'tokenizationSpecification': {
                'type': 'PAYMENT_GATEWAY',
                'parameters': {
                  'gateway': 'example',
                  'gatewayMerchantId': 'exampleGatewayMerchantId',
                },
              },
            },
          ],
          'transactionInfo': {
            'totalPriceStatus': 'FINAL',
            'totalPrice': '15.77',
            'currencyCode': 'USD',
          },
        }),
      },
    };

Zawartość obiektu tokenizationSpecification będzie inna w przypadku każdej bramy płatności. Tabela poniżej zawiera parametry używane przez każdą bramę:

PRZYKŁAD

"parameters": {
  "gateway": "example",
  "gatewayMerchantId": "exampleGatewayMerchantId"
}

ACI

"parameters": {
  "gateway": "aciworldwide",
  "gatewayMerchantId": "YOUR_ENTITY_ID"
}

ADADEN

"parameters": {
  "gateway": "adyen",
  "gatewayMerchantId": "YOUR_MERCHANT_ACCOUNT_NAME"
}

ALFA-BANK

"parameters": {
  "gateway": "alfabank",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

BLUE_MEDIA

"parameters": {
  "gateway": "bluemedia",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

BLUESNAP

"parameters": {
  "gateway": "bluesnap",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

BRAINTREE

"parameters": {
  "gateway": "braintree",
  "braintree:apiVersion": "v1",
  "braintree:sdkVersion": braintree.client.VERSION,
  "braintree:merchantId": "YOUR_BRAINTREE_MERCHANT_ID",
  "braintree:clientKey": "YOUR_BRAINTREE_TOKENIZATION_KEY"
}

CHASE_PAYMENTECH

"parameters": {
  "gateway": "chase",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ACCOUNT_NUMBER"
}

PŁATNOŚĆ

"parameters": {
  "gateway": "checkoutltd",
  "gatewayMerchantId": "YOUR_PUBLIC_KEY"
}

CLOUDPAYMENTS

"parameters": {
  "gateway": "cloudpayments",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

CYBERSOURCE

"parameters": {
  "gateway": "cybersource",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}

Przenoszenie danych

"parameters": {
  "gateway": "datatrans",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}

EBANX

"parameters": {
  "gateway": "ebanx",
  "gatewayMerchantId": "YOUR_PUBLIC_INTEGRATION_KEY"
}

FIRST_DATA

"parameters": {
  "gateway": "firstdata",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}

GLOBAL_PAYMENTS

"parameters": {
  "gateway": "globalpayments",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}

GOPAY

"parameters": {
  "gateway": "gopay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

HITRUST

"parameters": {
  "gateway": "hitrustpay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

IMSOLUTIONS

"parameters": {
  "gateway": "imsolutions",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}

LYRA

"parameters": {
  "gateway": "lyra",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

MPGS

"parameters": {
  "gateway": "mpgs",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

MONEY_MAIL_RU

"parameters": {
  "gateway": "moneymailru",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

NEWEBPAY

"parameters": {
  "gateway": "newebpay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

NEXI

"parameters": {
  "gateway": "nexi",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

NMI

"parameters": {
  "gateway": "creditcall",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

PAYSAFE

"parameters": {
  "gateway": "paysafe",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

PŁATNOŚĆ

"parameters": {
  "gateway": "payture",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

PAYU

"parameters": {
  "gateway": "payu",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

PRZELEWY24

"parameters": {
  "gateway": "przelewy24",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}

RBKMONEY

"parameters": {
  "gateway": "rbkmoney",
  "gatewayMerchantId": "YOUR_MERCHANT_ID"
}

SBERBank

"parameters": {
  "gateway": "sberbank",
  "gatewayMerchantId": "YOUR_ORGANIZATION_NAME"
}

KWALIFIKACJA

"parameters": {
  "gateway": "square",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

PRZEWODNIK

"parameters": {
  "gateway": "stripe",
  "stripe:version": "2018-10-31",
  "stripe:publishableKey": "YOUR_PUBLIC_STRIPE_KEY"
}

TAPPAY

"parameters": {
  "gateway": "tappay",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

TINKOFF

"parameters": {
  "gateway": "tinkoff",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

UNITELLER

"parameters": {
  "gateway": "uniteller",
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"
}

VANTIV

"parameters": {
  "gateway": "vantiv",
  "vantiv:merchantPayPageId": "YOUR_PAY_PAGE_ID",
  "vantiv:merchantOrderId": "YOUR_ORDER_ID",
  "vantiv:merchantTransactionId": "YOUR_TRANSACTION_ID",
  "vantiv:merchantReportGroup": "*web"
}

WORLDPAY

"parameters": {
  "gateway": "worldpay",
  "gatewayMerchantId": "YOUR_WORLDPAY_MERCHANT_ID"
}

YANDEX

"parameters": {
  "gateway": "yandexcheckout",
  "gatewayMerchantId": "YOUR_SHOP_ID"
}

Zapisz dane zamówienia w parametrze sesji

Zapisz dane o zamówieniu w parametrze sesji. Obiekt kolejności będzie używany w różnych scenach podczas tej samej sesji.

conv.session.params.order = {
    '@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
    order: order,
    orderOptions: orderOptions,
    presentationOptions: presentationOptions,
    paymentParameters: paymentParameters
};

Proponowanie zamówienia

Po utworzeniu zamówienia musisz przedstawić je użytkownikowi, aby potwierdzić lub odrzucić. Aby to zrobić, przejdź do sceny, w której podejmuje się decyzję o transakcji.

Utwórz scenę decyzji o transakcji

Na karcie Sceny dodaj nową scenę o nazwie TransactionDecision.
W sekcji Wypełnienie boksu kliknij +, by dodać nowy boks.
W sekcji Wybierz typ kliknij actions.type.TransactionDecisionValue jako typ boksu.
W polu nazwy boksu wpisz nazwę TransactionDecision.
Zaznacz pole wyboru Dostosuj odpowiedź do wartości boksu (domyślnie włączone).
W sekcji Skonfiguruj przedział wybierz z menu Użyj parametru sesji.
W sekcji Skonfiguruj przedział wpisz w polu tekstowym nazwę parametru sesji używanego do przechowywania zamówienia (tj. $session.params.order).
Kliknij Zapisz.

Aby wypełnić boks TransactionDecisionValue, Asystent inicjuje wbudowaną funkcję, w której przekazana właściwość Order jest renderowana bezpośrednio na „karcie podglądu koszyka”. Użytkownik może powiedzieć „złóż zamówienie”, odrzucić transakcję, zmienić opcję płatności, np. kartę kredytową lub adres, lub poprosić o zmianę zawartości zamówienia.

Na tym etapie użytkownik może też poprosić o zmianę zamówienia. W takim przypadku upewnij się, że po realizacji procesu składania koszyka Twoje zamówienia mogą obsługiwać żądania zmiany zamówień.

Wynik obsługi transakcji

Gdy boks TransactionDecisionValue jest wypełniony, odpowiedź użytkownika na decyzję o transakcji jest przechowywana w parametrze sesji. Zawiera ona:

ORDER_ACCEPTED,
ORDER_REJECTED,
DELIVERY_ADDRESS_UPDATED,
CART_CHANGE_REQUESTED
USER_CANNOT_TRANSACT

Aby przetworzyć wynik decyzji dotyczącej transakcji:

Na karcie Sceny wybierz nowo utworzoną scenę TransactionDecision.
W sekcji Warunek kliknij +, by dodać nowy warunek.

W polu tekstowym wpisz poniższą składnię warunku, by sprawdzić stan powodzenia:

scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

Najedź kursorem na nowo dodany warunek i kliknij strzałkę w górę, aby umieścić go przed if scene.slots.status == "FINAL".

Włącz opcję Wyślij potwierdzenia, w której wyświetli się prosta informacja o zakończeniu zamówienia.

candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction completed! Your order
            $session.params.TransactionDecision.order.merchantOrderId is all
            set!

W sekcji Przejście wybierz Zakończ rozmowę, aby zakończyć rozmowę.
W sekcji Warunek kliknij +, by dodać nowy warunek.

W polu tekstowym wpisz tę składnię warunku, by sprawdzić, czy nie spełnione są warunki:

  scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"

Najedź kursorem na nowo dodany warunek i kliknij strzałkę w górę, aby umieścić go przed if scene.slots.status == "FINAL".

Włącz opcję Wyślij potwierdzenia i powiadamiaj użytkownika, że jego zamówienie zostało odrzucone:

candidates:
  - first_simple:
      variants:
        - speech: Look like you don't want to order anything. Goodbye.

W sekcji Przejście wybierz Zakończ rozmowę, aby zakończyć rozmowę.
Wybierz warunek else if scene.slots.status == "FINAL".

Włącz Wyślij potwierdzenia i uzyskaj proste powiadomienie z informacją, że klient nie może dokonać transakcji:

candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction failed with status
            $session.params.TransactionDecision.transactionDecision

W sekcji Przejście wybierz Zakończ rozmowę, aby zakończyć rozmowę, jeśli użytkownik nie może dokonać transakcji.

Sfinalizuj zamówienie i wyślij potwierdzenie

Gdy boks TransactionDecisionValue zwraca wynik ORDER_ACCEPTED, musisz natychmiast wykonać wszystkie działania niezbędne do „potwierdzenia” zamówienia (np. zachowanie go w Twojej bazie danych i obciążenie użytkownika).

Możesz zakończyć rozmowę tą odpowiedzią, ale musisz dodać prostą odpowiedź, aby podtrzymać rozmowę. Gdy podasz ten początkowy fragment orderUpdate, użytkownik zobaczy „zwiiętą kartę z potwierdzeniem” wraz z resztą odpowiedzi. Zawiera ona potwierdzenie, które użytkownik znalazł w historii zamówień.

Po potwierdzeniu zamówienia obiekt może zawierać userVisibleOrderId, czyli identyfikator użytkownika widoczny w zamówieniu. W tym polu możesz ponownie wykorzystać merchantOrderId.

Część obiektu OrderUpdate musi zawierać obiekt dalszych działań, który wyświetla się w postaci adresów URL u dołu szczegółów zamówienia, które użytkownik może znaleźć w historii zamówień Asystenta.

Do każdego zamówienia musisz podać co najmniej działanie VIEW_DETAILS. Powinien zawierać precyzyjny link do reprezentacji zamówienia w aplikacji mobilnej lub na stronie.
Oprócz e-maila z potwierdzeniem rozmowy w wątku akcji musisz też wysłać formalne potwierdzenie e-mailem, które spełnia wszystkie wymagania prawne wymagane do przeprowadzenia transakcji.

Aby wysłać wstępną aktualizację zamówienia:

Na karcie Sceny wybierz scenę TransactionDecision.

W sekcji Warunek wybierz warunek, który sprawdzi wynik: ORDER_ACCEPTED

  scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

W przypadku tego warunku włącz Wywołaj webhooka i podaj nazwę modułu obsługi intencji, na przykład update_order.

W kodzie webhook dodaj moduł obsługi intencji do wysyłania początkowej aktualizacji zamówienia:

app.handle('update_order', conv => {
  const currentTime = new Date().toISOString();
  let order = conv.session.params.TransactionDecision.order;
  conv.add(new OrderUpdate({
    'updateMask': {
      'paths': [
        'purchase.status',
        'purchase.user_visible_status_label'
      ]
    },
    'order': {
      'merchantOrderId': order.merchantOrderId,
      'lastUpdateTime': currentTime,
      'purchase': {
        'status': 'CONFIRMED',
        'userVisibleStatusLabel': 'Order confirmed'
      },
    },
    'reason': 'Reason string
  }));
});

Wysyłanie aktualizacji zamówień

Musisz informować użytkownika o stanie zamówienia w trakcie jego trwania. Przesyłaj aktualizacje zamówień użytkowników, wysyłając żądania HTTP PATCH do interfejsu Orders API ze stanem i szczegółami zamówienia.

Konfigurowanie żądań asynchronicznych do interfejsu Orders API

Żądania aktualizacji zamówień wysyłane do interfejsu Orders API są autoryzowane przez token dostępu. Aby przeprowadzić aktualizację zamówienia w interfejsie Orders API, pobierz klucz konta usługi JSON powiązany z Twoim projektem Actions Console, a następnie wymień klucz konta usługi na token okaziciela, który można przekazać do nagłówka Authorization żądania HTTP.

Aby pobrać klucz konta usługi, wykonaj te czynności:

W konsoli Google Cloud kliknij Menu ☰ > Interfejsy API i usługi > Dane logowania > Utwórz dane logowania > Klucz konta usługi.
W sekcji Service Account (Konto usługi) wybierz New Service Account (Nowe konto usługi).
Ustaw konto usługi na service-account.
Ustaw Rolę na Projekt > Właściciel.
Ustaw typ klucza na JSON.
Kliknij Utwórz.
Na komputer lokalny zostanie pobrany prywatny klucz konta usługi JSON.

W kodzie aktualizacji zamówienia możesz wymienić klucz usługi na token okaziciela za pomocą biblioteki klienta interfejsów API Google i zakresu „https://www.googleapis.com/auth/actions.order.developer”. Instrukcje instalacji i przykłady znajdziesz w bibliotece klienta GitHub.

Możesz też odwołać się do order-update.js w przykładowym Node.js, aby zobaczyć przykładową wymianę kluczy.

Wysyłanie aktualizacji zamówień

Po wymianie klucza konta usługi na token okaziciela OAuth możesz wysyłać aktualizacje zamówień jako autoryzowane żądania PATCH do interfejsu Orders API.

URL interfejsu API zamówień: PATCH https://actions.googleapis.com/v3/orders/${orderId}

W odpowiedzi podaj te nagłówki:

"Authorization: Bearer token" z tokenem okaziciela OAuth, na który został wymieniony klucz konta usługi.
"Content-Type: application/json"

Żądanie PATCH powinno mieć treść JSON w tym formacie:

{ "orderUpdate": OrderUpdate }

Obiekt OrderUpdate składa się z następujących pól najwyższego poziomu:

updateMask – pola zamówienia, które chcesz zaktualizować. Aby zaktualizować stan zamówienia, ustaw wartość na purchase.status, purchase.userVisibleStatusLabel.
order – zawartość aktualizacji. Jeśli aktualizujesz zawartość zamówienia, ustaw jego wartość na zaktualizowany obiekt Order. Jeśli aktualizujesz stan zamówienia (np. z "CONFIRMED" na "SHIPPED"), obiekt zawiera te pola:
- merchantOrderId – identyfikator podany w obiekcie Order.
- lastUpdateTime – sygnatura czasowa tej aktualizacji.
- purchase – obiekt zawierający:
  - status – stan zamówienia PurchaseStatus, np. „SHIPPED” lub „DELIVERED”.
  - userVisibleStatusLabel – etykieta dla użytkowników ze szczegółami stanu, na przykład „Twoje zamówienie zostało wysłane i jest w drodze”.
userNotification (opcjonalnie) – obiekt userNotification, który może być wyświetlany na urządzeniu użytkownika po wysłaniu tej aktualizacji. Pamiętaj, że włączenie tego obiektu nie gwarantuje, że na urządzeniu użytkownika pojawi się powiadomienie.

Ten przykładowy kod pokazuje przykładowy plik OrderUpdate, który aktualizuje stan zamówienia do DELIVERED:

// Import the 'googleapis' module for authorizing the request.
const {google} = require('googleapis');
// Import the 'request-promise' module for sending an HTTP POST request.
const request = require('request-promise');
// Import the OrderUpdate class from the client library.
const {OrderUpdate} = require('@assistant/conversation');

// Import the service account key used to authorize the request.
// Replacing the string path with a path to your service account key.
// i.e. const serviceAccountKey = require('./service-account.json')

// Create a new JWT client for the Actions API using credentials
// from the service account key.
let jwtClient = new google.auth.JWT(
    serviceAccountKey.client_email,
    null,
    serviceAccountKey.private_key,
    ['https://www.googleapis.com/auth/actions.order.developer'],
    null,
);

// Authorize the client
let tokens = await jwtClient.authorize();

// Declare order update
const orderUpdate = new OrderUpdate({
    updateMask: {
      paths: [
        'purchase.status',
        'purchase.user_visible_status_label'
      ]
    },
    order: {
      merchantOrderId: orderId, // Specify the ID of the order to update
      lastUpdateTime: new Date().toISOString(),
      purchase: {
        status: 'DELIVERED',
        userVisibleStatusLabel: 'Order delivered',
      },
    },
    reason: 'Order status updated to delivered.',
});

// Set up the PATCH request header and body,
// including the authorized token and order update.
let options = {
  method: 'PATCH',
  uri: `https://actions.googleapis.com/v3/orders/${orderId}`,
  auth: {
    bearer: tokens.access_token,
  },
  body: {
    header: {
      isInSandbox: true,
    },
    orderUpdate,
  },
  json: true,
};

// Send the PATCH request to the Orders API.
try {
  await request(options);
} catch (e) {
  console.log(`Error: ${e}`);
}

Ustawianie stanu zakupu

Pole status w aktualizacji zamówienia musi opisywać jego aktualny stan. W polu order.purchase.status aktualizacji użyj jednej z tych wartości:

CREATED – zamówienie jest akceptowane przez użytkownika i utworzone „z perspektywy”, ale wymaga ręcznego przetwarzania po stronie zaplecza.
CONFIRMED – zamówienie jest aktywne i trwa jego przetwarzanie.
IN_PREPARATION – zamówienie jest przygotowywane do wysyłki/dostawy, na przykład podczas gotowania produktu.
READY_FOR_PICKUP – odbiorca może odebrać zamówienie.
DELIVERED – zamówienie zostało dostarczone do odbiorcy
OUT_OF_STOCK – co najmniej jeden produkt z zamówienia jest niedostępny.
CHANGE_REQUESTED – użytkownik poprosił o zmianę zamówienia i jest ona przetwarzana.
RETURNED – zamówienie zostało zwrócone przez użytkownika po dostarczeniu.
REJECTED – jeśli nie udało Ci się przetworzyć zamówienia, obciążyć go lub w inny sposób „aktywować” zamówienie.
CANCELLED – zamówienie zostało anulowane przez użytkownika.

Informacje o zamówieniach należy wysyłać w przypadku każdego stanu, który ma związek z daną transakcją. Jeśli na przykład transakcja wymaga ręcznego przetworzenia, aby zapisać zamówienie po jego złożeniu, wysyłaj aktualizację zamówienia CREATED do czasu zakończenia tego dodatkowego procesu. Nie każde zamówienie wymaga każdej wartości stanu.

Testowanie projektu

Podczas testowania projektu możesz włączyć tryb piaskownicy w konsoli Actions, aby przetestować działanie bez obciążania formy płatności. Aby włączyć tryb piaskownicy, wykonaj te czynności:

W konsoli działań kliknij Testuj.
Kliknij Ustawienia.
Włącz opcję Development Sandbox.

W przypadku transakcji fizycznych możesz też ustawić w przykładzie pole isInSandbox na true. To działanie jest równoważne włączeniu ustawienia trybu piaskownicy w konsoli Actions. Fragment kodu, który korzysta z isInSandbox, znajdziesz w sekcji Wysyłanie aktualizacji zamówień.

Rozwiązywanie problemów

Jeśli podczas testowania wystąpią problemy, przeczytaj instrukcje rozwiązywania problemów z transakcjami.