In diesem Leitfaden wird die Entwicklung eines Actions-Projekts beschrieben, das Transaktionen für physische Waren umfasst und Google Pay für Zahlungen verwendet.
Transaktionsablauf
Wenn in Ihrem Actions-Projekt physische Transaktionen mit vom Händler verwalteten Zahlungen verarbeitet werden, wird der folgende Ablauf verwendet:
- Informationen erfassen (optional): Je nach Art der Transaktion möchten Sie möglicherweise zu Beginn der Unterhaltung die folgenden Informationen vom Nutzer einholen:
- Transaktionsanforderungen validieren: Überprüfen Sie zu Beginn der Unterhaltung, ob der Nutzer die Anforderungen für eine Transaktion erfüllt, z. B. ob die Zahlungsinformationen richtig konfiguriert und verfügbar sind, bevor Sie den Einkaufswagen erstellen.
- Lieferadresse anfordern: Wenn für die Transaktion eine Lieferadresse erforderlich ist, fordern Sie eine vom Nutzer an.
- Bestellung zusammenstellen: Gehe mit dem Nutzer durch einen „Wagenbau“, bei dem er die Artikel auswählt, die er kaufen möchte.
- Bestellung vorschlagen: Sobald der Einkaufswagen fertig ist, schlagen Sie dem Nutzer die Bestellung vor, damit er bestätigen kann, dass sie korrekt ist. Wenn die Bestellung bestätigt wird, erhalten Sie eine Antwort mit Bestelldetails und einem Zahlungstoken.
- Bestellung abschließen und Beleg senden: Wenn die Bestellung bestätigt ist, aktualisieren Sie die Inventarverfolgung oder andere Auftragsausführungsdienste und senden Sie dann eine Quittung an den Nutzer.
- Bestellaktualisierungen senden: Biete dem Nutzer während der Laufzeit der Bestellung Aktualisierungen an, indem du PATCH-Anfragen an die Orders API sendest.
Einschränkungen und Richtlinien für Überprüfungen
Für Aktionen mit Transaktionen gelten zusätzliche Richtlinien. Die Überprüfung von Aktionen mit Transaktionen kann bis zu sechs Wochen dauern. Berücksichtigen Sie diese Zeit daher bei der Planung Ihres Release-Zeitplans. Achte darauf, dass du die Richtlinien für Transaktionen einhältst, bevor du deine Aktion zur Überprüfung einreichst, um den Überprüfungsprozess zu vereinfachen.
Du kannst Aktionen für physische Waren nur in den folgenden Ländern implementieren:
Australien Brasilien Kanada Indonesien |
Japan Mexiko Russland |
Singapur Thailand Türkei Vereinigtes Königreich USA |
Ihr Projekt erstellen
Ausführliche Beispiele für transaktionale Unterhaltungen finden Sie im Node.js-Transaktionsbeispiel.
Einrichtung
Beim Erstellen einer Aktion müssen Sie in der Actions Console angeben, dass Sie Transaktionen ausführen möchten.
So richten Sie Ihr Projekt und die Auftragsausführung ein:
- Erstellen Sie ein neues Projekt oder importieren Sie ein vorhandenes Projekt.
- Gehen Sie zu Bereitstellen > Verzeichnisinformationen.
Klicke unter Zusätzliche Informationen > Transaktionen auf das Kästchen neben "Verwenden deine Aktionen die Transactions API, um Transaktionen mit physischen Waren durchzuführen?".
1. Informationen erfassen (optional)
1a. Transaktionsanforderungen validieren (optional)
Sobald der Nutzer angegeben hat, dass er etwas kaufen möchte, solltest du prüfen, ob er eine Transaktion ausführen kann. Wenn deine Aktion aufgerufen wird, könnte sie beispielsweise fragen: "Möchtest du Schuhe bestellen oder deinen Kontostand überprüfen?" Wenn der Nutzer „Schuhe bestellen“ sagt, solltest du dafür sorgen, dass er fortfahren kann und ihm die Möglichkeit geben, alle Einstellungen zu korrigieren, die ihn daran hindern, die Transaktion fortzusetzen. Wechseln Sie dazu zu einer Szene, in der eine Prüfung der Transaktionsanforderungen durchgeführt wird.
Prüfung der Transaktionsanforderungen erstellen
- Fügen Sie auf dem Tab „Szenen“ eine neue Szene mit dem Namen
TransactionRequirementsCheck
hinzu. - Klicken Sie unter Slot-Füllung auf +, um eine neue Anzeigenfläche hinzuzufügen.
- Wählen Sie unter Typ auswählen
actions.type.TransactionRequirementsCheckResult
als Slottyp aus. - Geben Sie der Anzeigenfläche den Namen
TransactionRequirementsCheck
im Feld für den Slotnamen. - Klicken Sie das Kästchen Rückschreibe für Slotwert anpassen an (standardmäßig aktiviert).
- Klicken Sie auf Speichern.
Die Prüfung der Transaktionsanforderungen führt zu einem der folgenden Ergebnisse:
- Wenn die Anforderungen erfüllt sind, wird der Sitzungsparameter mit einer Erfolgsbedingung festgelegt und Sie können mit der Erstellung des Auftrags des Nutzers fortfahren.
- Wenn eine oder mehrere Anforderungen nicht erfüllt werden können, wird der Sitzungsparameter mit einer Fehlerbedingung festgelegt. In diesem Fall sollten Sie die Unterhaltung von der Transaktionserfahrung wegschwenken oder die Unterhaltung beenden.
- Wenn Fehler, die zum Fehlerstatus führen, vom Nutzer behoben werden können, wird er aufgefordert, diese Probleme auf seinem Gerät zu beheben. Wenn die Unterhaltung auf einer sprachgesteuerten Oberfläche stattfindet, wird eine Übergabe an das Smartphone des Nutzers initiiert.
Ergebnis der Prüfung für Transaktionsanforderungen verarbeiten
- Wählen Sie auf dem Tab Szenen die neu erstellte Szene
TransactionRequirementsCheck
aus. - Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
Geben Sie die folgende Bedingungssyntax in das Textfeld ein, um zu prüfen, ob die Erfolgsbedingung erfüllt ist:
scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
Bewegen Sie den Mauszeiger auf die soeben hinzugefügte Bedingung und klicken Sie auf den Pfeil nach oben, um sie vor
if scene.slots.status == "FINAL"
zu platzieren.Aktivieren Sie Aufforderungen senden und geben Sie den Nutzer mit einer einfachen Aufforderung an, eine Transaktion vorzunehmen:
candidates: - first_simple: variants: - speech: >- You are ready to purchase physical goods.
Wählen Sie unter Übergang eine andere Szene aus, damit der Nutzer die Unterhaltung fortsetzen und mit der Transaktion fortfahren kann.
Wählen Sie die Bedingung
else if scene.slots.status == "FINAL"
aus.Aktivieren Sie Aufforderungen senden und blenden Sie eine einfache Aufforderung ein, die den Nutzer darüber informiert, dass eine Transaktion nicht möglich ist:
candidates: - first_simple: variants: - speech: Transaction requirements check failed.
Wählen Sie unter Umstellung die Option Unterhaltung beenden aus, um die Unterhaltung zu beenden, wenn ein Nutzer keine Transaktionen vornehmen kann.
Lieferadresse anfordern
Wenn für Ihre Transaktion die Lieferadresse eines Nutzers erforderlich ist, sollten Sie diese beim Nutzer anfordern. Dies kann nützlich sein, um den Gesamtpreis und den Liefer-/Abholort zu ermitteln oder um sicherzustellen, dass sich der Nutzer in Ihrer Dienstleistungsregion befindet. Wechseln Sie dazu zu einer Szene, in der der Nutzer zur Eingabe seiner Lieferadresse aufgefordert wird.
Szene für Lieferadresse erstellen
- Fügen Sie auf dem Tab Szenen eine neue Szene mit dem Namen
DeliveryAddress
hinzu. - Klicken Sie unter Slot-Füllung auf +, um eine neue Anzeigenfläche hinzuzufügen.
- Wählen Sie unter Typ auswählen
actions.type.DeliveryAddressValue
als Slottyp aus. - Geben Sie der Anzeigenfläche den Namen
TransactionDeliveryAddress
im Feld für den Slotnamen. - Klicken Sie das Kästchen Rückschreibe für Slotwert anpassen an (standardmäßig aktiviert).
- Klicken Sie auf Speichern.
Beim Konfigurieren des Slots können Sie einen reason
angeben, mit dem Sie die Anfrage von Assistant zum Abrufen einer Adresse mit einem String voranstellen können.Der Standardstring für den Grund ist „zu wissen, wohin die Bestellung gesendet werden soll“. Daher könnte Assistant den Nutzer fragen: "Um zu wissen, wohin ich die Bestellung schicken soll, brauche ich Ihre Lieferadresse."
- Auf Oberflächen mit einem Bildschirm wählt der Nutzer aus, welche Adresse für die Transaktion verwendet werden soll. Wenn sie noch keine Adresse angegeben haben, können sie eine neue Adresse eingeben.
- Auf Oberflächen mit Sprachfunktion fragt Assistant den Nutzer um die Berechtigung zur Freigabe seiner Standardadresse für die Transaktion. Wenn sie noch keine Adresse angegeben haben, wird das Gespräch zur Teilnahme an ein Telefon weitergeleitet.
So verarbeiten Sie das Ergebnis für die Lieferadresse:
- Wählen Sie auf dem Tab Szenen die neu erstellte Szene
DeliveryAddress
aus. - Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
Geben Sie die folgende Bedingungssyntax in das Textfeld ein, um zu prüfen, ob die Erfolgsbedingung erfüllt ist:
scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"
Bewegen Sie den Mauszeiger auf die soeben hinzugefügte Bedingung und klicken Sie auf den Pfeil nach oben, um sie vor
if scene.slots.status == "FINAL"
zu platzieren.Aktivieren Sie Aufforderungen senden und zeigen Sie dem Nutzer durch eine einfache Aufforderung an, dass Sie seine Adresse erhalten haben:
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ählen Sie unter Übergang eine andere Szene aus, damit der Nutzer die Unterhaltung fortsetzen kann.
Wählen Sie die Bedingung
else if scene.slots.status == "FINAL"
aus.Aktivieren Sie Aufforderungen senden und blenden Sie eine einfache Aufforderung ein, die den Nutzer darüber informiert, dass eine Transaktion nicht möglich ist:
candidates: - first_simple: variants: - speech: I failed to get your delivery address.
Wählen Sie unter Umstellung die Option Unterhaltung beenden aus, um die Unterhaltung zu beenden, wenn ein Nutzer keine Transaktionen vornehmen kann.
Auftrag erstellen
Sobald Sie die benötigten Nutzerinformationen haben, erstellen Sie einen „Einkaufswagenbau“, der den Nutzer beim Erstellen einer Bestellung anleitet. Jede Aktion hat je nach Produkt oder Dienstleistung einen etwas anderen Montageablauf für den Warenkorb.
Bei der einfachsten Montage eines Einkaufswagens wählt der Nutzer Artikel aus einer Liste aus, die er seiner Bestellung hinzufügt. Sie können die Unterhaltung jedoch so gestalten, dass die User Experience vereinfacht wird. Sie könnten einen Warenkorbbau erstellen, der es dem Nutzer ermöglicht, seinen letzten Einkauf über eine einfache Ja-oder-Nein-Frage noch einmal zu bestellen. Sie können dem Nutzer auch ein Karussell oder eine Listenkarte mit den beliebtesten oder empfohlenen Artikeln präsentieren.
Wir empfehlen, umfangreiche Antworten zu verwenden, um die Optionen des Nutzers visuell darzustellen, aber auch die Unterhaltung so zu gestalten, dass der Nutzer seinen Warenkorb nur mit seiner Stimme erstellen kann. Einige Best Practices und Beispiele für die qualitativ hochwertige Montage von Einkaufswagen finden Sie in den Designrichtlinien.
Auftrag erstellen
Während der Unterhaltung musst du die Artikel sammeln, die ein Nutzer kaufen möchte, und dann ein Order
-Objekt erstellen.
Die Order
muss mindestens Folgendes enthalten:
buyerInfo
: Informationen zum Nutzer, der den Kauf tätigttransactionMerchant
: Informationen zum Händler, der die Bestellung durchgeführt hat.contents
: Der tatsächliche Inhalt des Auftrags, der alslineItems
aufgeführt ist.priceAttributes
: Preisdetails zur Bestellung, einschließlich der Gesamtkosten der Bestellung mit Rabatten und Steuern.
Informationen zum Erstellen des Einkaufswagens findest du in der Dokumentation zu Order
-Antworten. Je nach Reihenfolge müssen Sie unter Umständen andere Felder hinzufügen.
Der Beispielcode unten zeigt eine vollständige Bestellung mit optionalen Feldern:
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',
},
};
Auftrags- und Präsentationsoptionen erstellen
Bevor der Nutzer seine Bestellung bestätigt, wird ihm eine vorgeschlagene Bestellkarte angezeigt. Sie können die Darstellung dieser Karte für den Nutzer anpassen, indem Sie verschiedene Reihenfolge- und Präsentationsoptionen festlegen.
Nachfolgend finden Sie Bestell- und Präsentationsoptionen für eine Bestellung, für die eine Lieferadresse erforderlich ist, einschließlich der E-Mail-Adresse des Nutzers auf der Karte mit der Bestellbestätigung:
const orderOptions = {
'requestDeliveryAddress': true,
'userInfoOptions': {
'userInfoProperties': ['EMAIL']
}
};
const presentationOptions = {
'actionDisplayName': 'PLACE_ORDER'
};
Zahlungsparameter erstellen
Das paymentParameters
-Objekt enthält Tokenisierungsparameter, die sich je nach Google Pay-Auftragsverarbeiter ändern, den Sie verwenden möchten (z. B. Stripe, Braintree, ACI usw.).
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',
},
}),
},
};
Der Inhalt des Objekts tokenizationSpecification
ist je nach Zahlungsgateway unterschiedlich. Die folgende Tabelle zeigt die von jedem Gateway verwendeten Parameter:
"parameters": { "gateway": "example", "gatewayMerchantId": "exampleGatewayMerchantId" }
"parameters": { "gateway": "aciworldwide", "gatewayMerchantId": "YOUR_ENTITY_ID" }
"parameters": { "gateway": "adyen", "gatewayMerchantId": "YOUR_MERCHANT_ACCOUNT_NAME" }
"parameters": { "gateway": "alfabank", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "bluemedia", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "bluesnap", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "braintree", "braintree:apiVersion": "v1", "braintree:sdkVersion": braintree.client.VERSION, "braintree:merchantId": "YOUR_BRAINTREE_MERCHANT_ID", "braintree:clientKey": "YOUR_BRAINTREE_TOKENIZATION_KEY" }
"parameters": { "gateway": "chase", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ACCOUNT_NUMBER" }
"parameters": { "gateway": "checkoutltd", "gatewayMerchantId": "YOUR_PUBLIC_KEY" }
"parameters": { "gateway": "cloudpayments", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "cybersource", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "datatrans", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "ebanx", "gatewayMerchantId": "YOUR_PUBLIC_INTEGRATION_KEY" }
"parameters": { "gateway": "firstdata", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "globalpayments", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "gopay", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "hitrustpay", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "imsolutions", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "lyra", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "mpgs", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "moneymailru", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "newebpay", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "nexi", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "creditcall", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "paysafe", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "payture", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "payu", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "przelewy24", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "rbkmoney", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "sberbank", "gatewayMerchantId": "YOUR_ORGANIZATION_NAME" }
"parameters": { "gateway": "square", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "stripe", "stripe:version": "2018-10-31", "stripe:publishableKey": "YOUR_PUBLIC_STRIPE_KEY" }
"parameters": { "gateway": "tappay", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "tinkoff", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "uniteller", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "vantiv", "vantiv:merchantPayPageId": "YOUR_PAY_PAGE_ID", "vantiv:merchantOrderId": "YOUR_ORDER_ID", "vantiv:merchantTransactionId": "YOUR_TRANSACTION_ID", "vantiv:merchantReportGroup": "*web" }
"parameters": { "gateway": "worldpay", "gatewayMerchantId": "YOUR_WORLDPAY_MERCHANT_ID" }
"parameters": { "gateway": "yandexcheckout", "gatewayMerchantId": "YOUR_SHOP_ID" }
Bestelldaten im Sitzungsparameter speichern
Speichern Sie die Bestelldaten aus der Auftragsausführung in einem Sitzungsparameter. Das Order-Objekt wird szenenübergreifend für dieselbe Sitzung verwendet.
conv.session.params.order = {
'@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
order: order,
orderOptions: orderOptions,
presentationOptions: presentationOptions,
paymentParameters: paymentParameters
};
Auftrag vorschlagen
Nachdem Sie einen Auftrag erstellt haben, müssen Sie ihn dem Nutzer zur Bestätigung oder zur Ablehnung vorlegen. Wechseln Sie dazu zu einer Szene, die eine Transaktionsentscheidung ausführt.
Szene für Transaktionsentscheidung erstellen
- Fügen Sie auf dem Tab Szenen eine neue Szene mit dem Namen
TransactionDecision
hinzu. - Klicken Sie unter Slot-Füllung auf +, um eine neue Anzeigenfläche hinzuzufügen.
- Wählen Sie unter Typ auswählen
actions.type.TransactionDecisionValue
als Slottyp aus. - Geben Sie der Anzeigenfläche den Namen
TransactionDecision
im Feld für den Slotnamen. - Klicken Sie das Kästchen Rückschreibe für Slotwert anpassen an (standardmäßig aktiviert).
- Wählen Sie unter Slot konfigurieren im Drop-down-Menü die Option Sitzungsparameter verwenden aus.
- Geben Sie unter Slot konfigurieren den Namen des Sitzungsparameters ein,der zum Speichern der Bestellung im Textfeld verwendet wird (z.B.
$session.params.order
). - Klicken Sie auf Speichern.
Beim Versuch, einen TransactionDecisionValue
-Slot zu füllen, initiiert Assistant eine integrierte Funktion, bei der die übergebene Order
direkt auf einer „Warenkorbvorschaukarte“ gerendert wird. Der Nutzer kann „Bestellung aufgeben“ sagen, die Transaktion ablehnen, eine Zahlungsoption wie Kreditkarte oder Adresse ändern oder eine Änderung des Bestellinhalts anfordern.
An dieser Stelle kann der Nutzer auch Änderungen an der Bestellung anfordern. In diesem Fall sollten Sie dafür sorgen, dass die Auftragsausführung nach Abschluss der Warenkorbmontage Anfragen zu Bestelländerungen bearbeiten kann.
Transaktionsentscheidungsergebnis verarbeiten
Wenn ein TransactionDecisionValue
-Slot gefüllt wird, wird die Antwort des Nutzers auf die Transaktionsentscheidung in einem Sitzungsparameter gespeichert. Dieser Wert enthält Folgendes:
ORDER_ACCEPTED
,ORDER_REJECTED
,DELIVERY_ADDRESS_UPDATED
,CART_CHANGE_REQUESTED
USER_CANNOT_TRANSACT
.
So verarbeiten Sie das Ergebnis einer Transaktionsentscheidung:
- Wählen Sie auf dem Tab Szenen die neu erstellte Szene
TransactionDecision
aus. - Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
Geben Sie die folgende Bedingungssyntax in das Textfeld ein, um zu prüfen, ob die Erfolgsbedingung erfüllt ist:
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
Bewegen Sie den Mauszeiger auf die soeben hinzugefügte Bedingung und klicken Sie auf den Pfeil nach oben, um sie vor
if scene.slots.status == "FINAL"
zu platzieren.Aktivieren Sie Aufforderungen senden und geben Sie eine einfache Aufforderung an, die den Nutzer darüber informiert, dass seine Bestellung abgeschlossen ist:
candidates: - first_simple: variants: - speech: >- Transaction completed! Your order $session.params.TransactionDecision.order.merchantOrderId is all set!
Wählen Sie unter Umstellung die Option Unterhaltung beenden aus.
Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
Geben Sie in das Textfeld die folgende Bedingungssyntax ein, um nach den Fehlerbedingungen zu suchen:
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"
Bewegen Sie den Mauszeiger auf die soeben hinzugefügte Bedingung und klicken Sie auf den Pfeil nach oben, um sie vor
if scene.slots.status == "FINAL"
zu platzieren.Aktivieren Sie Aufforderungen senden und zeigen Sie dem Nutzer mit einer einfachen Aufforderung an, dass die Bestellung abgelehnt wurde:
candidates: - first_simple: variants: - speech: Look like you don't want to order anything. Goodbye.
Wählen Sie unter Umstellung die Option Unterhaltung beenden aus.
Wählen Sie die Bedingung
else if scene.slots.status == "FINAL"
aus.Aktivieren Sie SendPrompts (Aufforderungen senden) und geben Sie dem Nutzer eine einfache Aufforderung an, damit er weiß, dass er keine Transaktion vornehmen kann:
candidates: - first_simple: variants: - speech: >- Transaction failed with status $session.params.TransactionDecision.transactionDecision
Wählen Sie unter Umstellung die Option Unterhaltung beenden aus, um die Unterhaltung zu beenden, wenn ein Nutzer keine Transaktionen vornehmen kann.
Bestellung abschließen und Beleg senden
Wenn der Slot TransactionDecisionValue
das Ergebnis ORDER_ACCEPTED
zurückgibt, müssen Sie sofort die Verarbeitung ausführen, die zum "Bestätigen" der Bestellung erforderlich ist. Sie können sie beispielsweise in Ihrer eigenen Datenbank speichern und dem Nutzer in Rechnung stellen.
Sie können die Unterhaltung mit dieser Antwort beenden, müssen aber eine einfache Antwort hinzufügen, um die Unterhaltung am Laufen zu halten. Wenn du diese anfängliche orderUpdate
angibst, sieht der Nutzer eine minimierte Belegkarte zusammen mit dem Rest deiner Antwort. Diese Karte spiegelt den Beleg wider, den der Nutzer in seinem Bestellverlauf findet.
Während der Bestellbestätigung kann das Bestellobjekt eine userVisibleOrderId
enthalten. Das ist die ID, die der Nutzer für die Bestellung sieht. Sie können die merchantOrderId
für dieses Feld wiederverwenden.
Ein Teil des OrderUpdate
-Objekts muss ein Follow-up-Action-Objekt enthalten, das sich in Form von URL-Schaltflächen am Ende der Bestelldetails befindet, die der Nutzer in seinem Assistant-Bestellverlauf finden kann.
- Für jede Bestellung müssen Sie mindestens eine
VIEW_DETAILS
-Folgeaktion angeben. Dieser sollte einen Deeplink zur Darstellung der Bestellung in Ihrer mobilen App oder Website enthalten. - Zusätzlich zur Empfangskarte in der Unterhaltung deiner Aktion musst du per E-Mail einen formellen Beleg senden, der alle rechtlichen Anforderungen für die Durchführung einer Transaktion erfüllt.
So senden Sie eine erste Bestellaktualisierung:
- Wähle auf dem Tab Szenen deine
TransactionDecision
-Szene aus. Wählen Sie unter Bedingung die Bedingung aus, die das Erfolgsergebnis
ORDER_ACCEPTED
prüft:scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
Aktivieren Sie für diese Bedingung Webhook aufrufen und geben Sie einen Intent-Handler-Namen wie
update_order
an.Fügen Sie dem Webhook-Code einen Intent-Handler hinzu, um eine anfängliche Bestellaktualisierung zu senden:
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 })); });
Bestellaktualisierungen senden
Sie müssen den Nutzer während der gesamten Lebensdauer über den Status der Bestellung informieren. Senden Sie dem Nutzer Bestellaktualisierungen, indem Sie HTTP-PATCH-Anfragen mit Bestellstatus und -details an die Orders API senden.
Asynchrone Anfragen an die Orders API einrichten
Anfragen zur Bestellaktualisierung an die Orders API werden durch ein Zugriffstoken autorisiert. Wenn du eine Bestellaktualisierung mit PATCH für die Orders API durchführen möchtest, lade einen JSON-Dienstkontoschlüssel herunter, der mit deinem Actions Console-Projekt verknüpft ist, und tauschen Sie den Dienstkontoschlüssel gegen ein Inhabertoken aus, das an den Authorization
-Header der HTTP-Anfrage übergeben werden kann.
Führen Sie die folgenden Schritte aus, um Ihren Dienstkontoschlüssel abzurufen:
- Gehen Sie in der Google Cloud Console zu Menü ⋮ > APIs und Dienste > Anmeldedaten > Anmeldedaten erstellen > Dienstkontoschlüssel.
- Wählen Sie unter Dienstkonto die Option Neues Dienstkonto aus.
- Legen Sie das Dienstkonto auf
service-account
fest. - Stellen Sie die Rolle auf Projekt > Inhaber ein.
- Legen Sie den Schlüsseltyp auf JSON fest.
- Wählen Sie Erstellen aus.
- Ein privater JSON-Dienstkontoschlüssel wird auf Ihren lokalen Computer heruntergeladen.
Im Code für die Aktualisierung Ihrer Bestellung können Sie Ihren Dienstschlüssel mithilfe der Google APIs-Clientbibliothek und dem Bereich "https://www.googleapis.com/auth/actions.order.developer" gegen ein Inhabertoken austauschen. Installationsschritte und Beispiele finden Sie auf der GitHub-Seite der API-Clientbibliothek.
Als Beispiel für einen Schlüsselaustausch können Sie auch auf order-update.js
in unserem Node.js-Beispiel verweisen.
Bestellaktualisierungen senden
Nachdem Sie Ihren Dienstkontoschlüssel gegen ein OAuth-Inhabertoken ausgetauscht haben, können Sie Bestellaktualisierungen als autorisierte PATCH-Anfragen an die Orders API senden.
URL der Orders API:
PATCH https://actions.googleapis.com/v3/orders/${orderId}
Geben Sie in Ihrer Anfrage die folgenden Header an:
"Authorization: Bearer token"
durch das OAuth-Inhabertoken, gegen das Sie Ihren Dienstkontoschlüssel ausgetauscht haben."Content-Type: application/json"
.
Die PATCH-Anfrage sollte einen JSON-Text im folgenden Format haben:
{ "orderUpdate": OrderUpdate }
Das Objekt OrderUpdate
besteht aus den folgenden Feldern der obersten Ebene:
updateMask
: die Felder des Auftrags, den Sie aktualisieren Wenn Sie den Bestellstatus aktualisieren möchten, legen Sie den Wert aufpurchase.status, purchase.userVisibleStatusLabel
fest.order
: Der Inhalt des Updates. Wenn du den Inhalt der Bestellung aktualisierst, lege den Wert auf das aktualisierteOrder
-Objekt fest. Wenn Sie den Status der Bestellung aktualisieren (z. B. von"CONFIRMED"
zu"SHIPPED"
), enthält das Objekt die folgenden Felder:merchantOrderId
: Dies ist die ID, die Sie imOrder
-Objekt festgelegt haben.lastUpdateTime
: Der Zeitstempel dieser Aktualisierung.purchase
: ein Objekt, das Folgendes enthält:status
: Der Status der Bestellung alsPurchaseStatus
, z. B. „SHIPPED
“ oder „DELIVERED
“.userVisibleStatusLabel
: ein für den Nutzer sichtbares Label mit Details zum Bestellstatus, z. B. „Ihre Bestellung wurde versandt und ist unterwegs“.
userNotification
(optional) – EinuserNotification
-Objekt, das auf dem Gerät des Nutzers angezeigt werden kann, wenn dieses Update gesendet wird. Das Hinzufügen dieses Objekts garantiert jedoch nicht, dass eine Benachrichtigung auf dem Gerät des Nutzers erscheint.
Der folgende Beispielcode zeigt ein OrderUpdate
-Beispiel, das den Status der Bestellung in DELIVERED
aktualisiert:
// 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}`);
}
Kaufstatus festlegen
Der status
einer Bestellaktualisierung muss eine Beschreibung des aktuellen Status der Bestellung enthalten. Verwenden Sie im Feld order.purchase.status
des Updates einen der folgenden Werte:
CREATED
: Die Reihenfolge wird vom Nutzer akzeptiert und aus Sicht deiner Aktion „erstellt“, erfordert jedoch eine manuelle Verarbeitung auf deinem Back-End.CONFIRMED
: Die Bestellung ist aktiv und wird zwecks Auftragsausführung verarbeitet.IN_PREPARATION
: Die Bestellung wird für den Versand/die Lieferung vorbereitet, z. B. wenn Essen gekocht oder ein Artikel verpackt wird.READY_FOR_PICKUP
: Die Bestellung kann vom Empfänger abgeholt werden.DELIVERED
– Bestellung wurde an den Empfänger zugestelltOUT_OF_STOCK
: Mindestens ein Artikel in der Bestellung ist nicht auf Lager.CHANGE_REQUESTED
: Der Nutzer hat eine Änderung an der Bestellung angefordert und die Änderung wird verarbeitet.RETURNED
: Die Bestellung wurde vom Nutzer nach der Lieferung zurückgegeben.REJECTED
: Wenn Sie die Bestellung nicht verarbeiten, in Rechnung stellen oder anderweitig „aktivieren“ konnten.CANCELLED
: Die Bestellung wurde vom Nutzer storniert.
Sie sollten Bestellaktualisierungen für jeden für Ihre Transaktion relevanten Status senden. Wenn Ihre Transaktion beispielsweise eine manuelle Verarbeitung erfordert, um die Bestellung nach ihrer Aufgabe zu protokollieren, senden Sie eine CREATED
-Bestellaktualisierung, bis die zusätzliche Verarbeitung abgeschlossen ist. Nicht für jede Bestellung ist jeder Statuswert erforderlich.
Projekt testen
Beim Testen deines Projekts kannst du den Sandbox-Modus in der Actions Console aktivieren, um deine Aktion zu testen, ohne eine Zahlungsmethode zu belasten. So aktivieren Sie den Sandbox-Modus:
- Klicken Sie in der Actions Console im Navigationsbereich auf Test.
- Klicke auf Einstellungen.
- Aktivieren Sie die Option Entwicklungs-Sandbox.
Für physische Transaktionen können Sie das Feld isInSandbox
in Ihrem Beispiel auch auf true
setzen. Diese Aktion entspricht dem Aktivieren der Einstellung für den Sandbox-Modus in der Actions Console. Ein Code-Snippet, in dem isInSandbox
verwendet wird, findest du im Abschnitt Bestellaktualisierungen senden.
Fehlerbehebung
Wenn während des Tests Probleme auftreten, lesen Sie unsere Schritte zur Fehlerbehebung für Transaktionen.