In diesem Leitfaden wird erläutert, wie Sie ein Actions-Projekt entwickeln, das Transaktionen für physische Waren umfasst und Google Pay für Zahlungen verwendet.
Transaktionsablauf
Wenn dein Actions-Projekt physische Transaktionen mit vom Händler verwalteten Zahlungen verarbeitet, wird der folgende Ablauf verwendet:
- Informationen erfassen (optional): Je nach Art der Transaktion sollten Sie zu Beginn der Unterhaltung die folgenden Informationen einholen:
- Transaktionsanforderungen validieren: Zu Beginn der Unterhaltung sollten Sie prüfen, ob der Nutzer die Anforderungen für eine Transaktion erfüllt, z. B. ob die Zahlungsinformationen korrekt konfiguriert und verfügbar sind, bevor der Einkaufswagen erstellt wird.
- Lieferadresse anfordern: Wenn für die Transaktion eine Lieferadresse erforderlich ist, erkundige dich beim Nutzer.
- Erstellen Sie die Bestellung: Gehen Sie den Nutzer durch eine "Wagenbaugruppe", in der 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 ihre Richtigkeit bestätigen kann. Wenn die Bestellung bestätigt wurde, erhältst du eine Antwort mit Bestelldetails und einem Zahlungstoken.
- Bestellung abschließen und Beleg senden: Aktualisieren Sie nach der Bestätigung der Bestellung Ihr Inventar-Tracking- oder andere Auftragsausführungsdienste und senden Sie dann einen Beleg an den Nutzer.
- Bestellaktualisierungen senden: Im Laufe der Laufzeit der Auftragsausführung können Sie die Nutzerbestellungen aktualisieren, indem Sie PATCH-Anfragen an die Orders API senden.
Einschränkungen und Überprüfungsrichtlinien
Für Aktionen mit Transaktionen gelten zusätzliche Richtlinien. Es kann bis zu sechs Wochen dauern, bis Aktionen mit Transaktionen überprüft werden. Berücksichtigen Sie dies bei der Planung Ihres Release-Zeitplans. Achten Sie darauf, dass Sie die Richtlinien für Transaktionen einhalten, bevor Sie Ihre Aktion zur Überprüfung einreichen. Dies vereinfacht die Überprüfung.
Du kannst Aktionen, die physische Waren verkaufen, nur in den folgenden Ländern bereitstellen:
|
Australien Brasilien Kanada Indonesien |
Japan Mexiko Russland |
Singapur Thailand Türkei Vereinigtes Königreich USA |
Projekt erstellen
Ausführliche Beispiele für transaktionale Unterhaltungen finden Sie im Node.js-Transaktionsbeispiel.
Einrichtung
Beim Erstellen Ihrer Aktion müssen Sie angeben, dass Sie Transaktionen in der Aktionen-Konsole durchführen möchten.
So richten Sie Ihr Projekt und die Auftragsausführung ein:
- Erstellen Sie ein neues Projekt oder importieren Sie ein vorhandenes Projekt.
- Klicken Sie auf Bereitstellen > Verzeichnisinformationen.
Klicke unter Zusätzliche Informationen > Transaktionen auf das Kästchen "Verwenden Sie deine Actions API für Transaktionen zu physischen Waren?".
1. Informationen sammeln (optional)
1a. Transaktionsanforderungen bestätigen (optional)
Sobald der Nutzer angegeben hat, dass er etwas kaufen möchte, solltest du prüfen, ob er eine Transaktion durchführen kann. Wenn Sie beispielsweise anrufen, werden Sie gefragt, ob Sie Schuhe bestellen oder Ihren Kontostand abrufen möchten. Wenn der Nutzer „Schuhe bestellen“ sagt, sollte er fortfahren und es den Kunden ermöglichen, Einstellungen zu ändern, die ihn daran hindern, mit der Transaktion fortzufahren. Dazu solltest du zu einer Szene wechseln, in der die Transaktionsanforderungen geprüft werden.
Szene-Prüfprüfung für Transaktionsanforderungen erstellen
- Fügen Sie auf dem Tab „Szenen“ eine neue Szene mit dem Namen
TransactionRequirementsCheckhinzu. - Klicken Sie unter Slot-Füllung auf +, um einen neuen Slot hinzuzufügen.
- Wählen Sie unter Typ auswählen
actions.type.TransactionRequirementsCheckResultals Slottyp aus. - Geben Sie im Feld für den Namen der Anzeigenfläche den Namen
TransactionRequirementsCheckein. - Aktivieren Sie das Kästchen Slotback-Rückbuchung anpassen (standardmäßig aktiviert).
- Klicken Sie auf Speichern.
Eine Prüfung der Transaktionsanforderungen führt zu einem der folgenden Ergebnisse:
- Wenn die Anforderungen erfüllt sind, wird der Sitzungsparameter mit einer Erfolgsbedingung festgelegt. Sie können dann mit der Erstellung der Nutzeranfrage fortfahren.
- Wenn eine oder mehrere Anforderungen nicht erfüllt werden können, wird für den Sitzungsparameter eine Fehlerbedingung festgelegt. In diesem Fall sollten Sie die Unterhaltung vom transaktionalen Ansatz entfernen oder die Unterhaltung beenden.
- Wenn Fehler, die zum Fehlerstatus führen, vom Nutzer behoben werden können, werden sie aufgefordert, diese Probleme auf ihrem Gerät zu beheben. Wenn die Unterhaltung auf einer sprachbasierten Oberfläche stattfindet, wird ein Handoff an das Smartphone des Nutzers initiiert.
Ergebnis der Überprüfung der Transaktionsanforderungen prüfen
- Wählen Sie auf dem Tab Szenen die neu erstellte Szene
TransactionRequirementsCheckaus. - Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
Geben Sie in das Textfeld die folgende Syntax für Bedingungen ein, um die Erfolgsbedingung zu prüfen:
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 Aufwärtspfeil, um sie vor
if scene.slots.status == "FINAL"zu platzieren.Aktivieren Sie die Option Aufforderungen senden und geben Sie eine einfache Aufforderung an, dass der Nutzer bereit für eine Transaktion ist.
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 einer Transaktion fortfahren kann.
Wählen Sie die Bedingung
else if scene.slots.status == "FINAL"aus.Aktivieren Sie die Option Senden von Aufforderungen und informieren Sie den Nutzer, dass er keine Transaktion durchführen kann:
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 durchführen kann.
Lieferadresse anfordern
Wenn für die Transaktion die Lieferadresse eines Nutzers erforderlich ist, sollten Sie sie vom Nutzer anfordern. Dies kann nützlich sein, um den Gesamtpreis, den Liefer-/Abholort oder den Nutzer in Ihrer Einzugsregion zu ermitteln. Dazu wechseln Sie zu einer Szene, in der der Nutzer nach seiner Lieferadresse gefragt wird.
Adresse für Lieferadresse erstellen
- Fügen Sie auf dem Tab Szenen eine neue Szene mit dem Namen
DeliveryAddresshinzu. - Klicken Sie unter Slot-Füllung auf +, um einen neuen Slot hinzuzufügen.
- Wählen Sie unter Typ auswählen
actions.type.DeliveryAddressValueals Slottyp aus. - Geben Sie im Feld für den Namen der Anzeigenfläche den Namen
TransactionDeliveryAddressein. - Aktivieren Sie das Kästchen Slotback-Rückbuchung anpassen (standardmäßig aktiviert).
- Klicken Sie auf Speichern.
Wenn Sie den Slot konfigurieren, können Sie eine reason angeben, mit der sich die Anfrage von Assistant zum Abrufen einer Adresse mit einem String voranstellen lässt.Der Standardgrundstring ist „Weiß, wohin die Bestellung gesendet werden soll“. Assistant fordert den Nutzer daher möglicherweise an: „Um zu erfahren, wohin ich die Bestellung senden muss, benötige ich meine Lieferadresse.“
- Auf Oberflächen mit einem Bildschirm wählt der Nutzer die Adresse aus, die er für die Transaktion verwenden möchte. Wenn sie noch keine Adresse angegeben haben, können sie eine neue eingeben.
- Auf Plattformen, die nur eine Stimme haben, bittet Assistant den Nutzer um die Berechtigung, seine Standardadresse für die Transaktion freizugeben. Wenn sie noch keine Adresse angegeben haben, wird die Unterhaltung an ein Smartphone gesendet.
So verarbeiten Sie das Ergebnis der Lieferadresse:
- Wählen Sie auf dem Tab Szenen Ihre neu erstellte
DeliveryAddress-Szene aus. - Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
Geben Sie in das Textfeld die folgende Syntax für Bedingungen ein, um die Erfolgsbedingung zu prüfen:
scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"Bewegen Sie den Mauszeiger auf die soeben hinzugefügte Bedingung und klicken Sie auf den Aufwärtspfeil, um sie vor
if scene.slots.status == "FINAL"zu platzieren.Aktivieren Sie die Option Aufforderungen senden und teilen Sie dem Nutzer mit einer einfachen Aufforderung mit, 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.postalCodeWä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 die Option Senden von Aufforderungen und informieren Sie den Nutzer, dass er keine Transaktion durchführen kann:
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 durchführen kann.
Auftrag erstellen
Sobald Sie die benötigten Nutzerinformationen haben, erstellen Sie eine Website mit der Funktion „Wagenmontage“, über die der Nutzer eine Bestellung erstellt. Jede Aktion hat einen etwas anderen Ablauf beim Einkaufswagen, der dem Produkt oder der Dienstleistung entspricht.
Bei der einfachsten Montage kann ein Nutzer Elemente aus einer Liste auswählen, die seiner Bestellung hinzugefügt werden sollen. Sie können das Gespräch jedoch auch vereinfachen. Sie könnten beispielsweise eine Einkaufswagen-Installation erstellen, durch die der Nutzer seinen letzten Kauf über eine einfache Ja-oder-Nein-Frage noch einmal bestellen kann. Du kannst dem Nutzer auch eine Karussell- oder Listenkarte mit den wichtigsten empfohlenen Inhalten oder empfohlenen Inhalten präsentieren.
Wir empfehlen, Rich-Antworten zu verwenden, um die Optionen des Nutzers visuell darzustellen, aber das Gespräch so zu gestalten, dass der Nutzer den Einkaufswagen nur mit der Stimme erstellen kann. Einige Best Practices und Beispiele für hochwertige Montagemöglichkeiten für Einkaufswagen finden Sie in den Designrichtlinien.
Auftrag erstellen
Während des gesamten Gesprächs müssen Sie die Artikel erfassen, die ein Nutzer kaufen möchte, und dann ein Order-Objekt erstellen.
Order muss mindestens Folgendes enthalten:
buyerInfo: Informationen zum Nutzer, der den Kauf tätigt.transactionMerchant: Informationen zu dem Händler, der die Bestellung ermöglicht hat.contents: Der tatsächliche Inhalt der Bestellung, angegeben alslineItems.priceAttributes: Preisinformationen zur Bestellung, einschließlich der Gesamtkosten der Bestellung, einschließlich Rabatten und Steuern.
Informationen zum Erstellen des Einkaufswagens finden Sie in der Dokumentation zu Order. Je nach Reihenfolge müssen Sie unterschiedliche Felder angeben.
Der Beispielcode unten enthält eine vollständige Reihenfolge 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',
},
};
Optionen für Auftrag und Präsentation 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 Optionen für die Reihenfolge und Präsentation festlegen.
Im Folgenden finden Sie Optionen für die Bestellung und Präsentation, mit denen Sie eine Bestellung aufgeben können, für die eine Lieferadresse erforderlich ist, einschließlich der E-Mail-Adresse des Nutzers auf der Karte zur Bestellbestätigung:
const orderOptions = {
'requestDeliveryAddress': true,
'userInfoOptions': {
'userInfoProperties': ['EMAIL']
}
};
const presentationOptions = {
'actionDisplayName': 'PLACE_ORDER'
};
Zahlungsparameter erstellen
Das paymentParameters-Objekt enthält Tokenisierungsparameter, die sich davon unterscheiden, welchen Google Pay-Prozessor Sie verwenden möchten (z. B. Stripe, Braintree, ACI).
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 unterscheidet sich je nach Zahlungsgateway. In der folgenden Tabelle sehen Sie die von den einzelnen Gateways 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 Reihenfolgeobjekt wird für alle Szenen einer Sitzung verwendet.
conv.session.params.order = {
'@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
order: order,
orderOptions: orderOptions,
presentationOptions: presentationOptions,
paymentParameters: paymentParameters
};
Bestellung vorschlagen
Nachdem Sie einen Auftrag erstellt haben, müssen Sie ihn dem Nutzer zur Bestätigung oder Ablehnung vorlegen. Dazu sollten Sie zu einer Szene wechseln, in der eine Transaktionsentscheidung getroffen wird.
Szenario für Transaktionsentscheidung erstellen
- Fügen Sie auf dem Tab Szenen eine neue Szene mit dem Namen
TransactionDecisionhinzu. - Klicken Sie unter Slot-Füllung auf +, um einen neuen Slot hinzuzufügen.
- Wählen Sie unter Typ auswählen
actions.type.TransactionDecisionValueals Slottyp aus. - Geben Sie im Feld für den Namen der Anzeigenfläche den Namen
TransactionDecisionein. - Aktivieren Sie das Kästchen Slotback-Rückbuchung anpassen (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,mit dem die Bestellung im Textfeld gespeichert wird (z.B.
$session.params.order). - Klicken Sie auf Speichern.
Wenn versucht wird, einen TransactionDecisionValue-Slot zu füllen, initiiert Assistant eine integrierte Oberfläche, in der das übergebene Order-Element direkt auf einer „Einkaufswagenvorschau“-Karte gerendert wird. Der Nutzer kann „Bestellung aufgeben“ sagen, die Transaktion ablehnen, eine Zahlungsoption wie die Kreditkarte oder Adresse ändern oder den Inhalt der Bestellung ändern.
Der Nutzer kann zu diesem Zeitpunkt auch Änderungen an der Bestellung anfordern. In diesem Fall sollten Sie dafür sorgen, dass die Auftragsausführung Anfragen für Bestelländerungen verarbeiten kann, nachdem die Website zusammengesetzt wurde.
Ergebnis der Transaktionsentscheidung verarbeiten
Wenn ein TransactionDecisionValue-Slot gefüllt ist, wird die Antwort des Nutzers auf die Transaktionsentscheidung in einem Sitzungsparameter gespeichert. Dieser Wert enthält Folgendes:
ORDER_ACCEPTED,ORDER_REJECTEDDELIVERY_ADDRESS_UPDATEDCART_CHANGE_REQUESTEDUSER_CANNOT_TRANSACT.
So verarbeiten Sie das Ergebnis einer Transaktionsentscheidung:
- Wählen Sie auf dem Tab Szenen Ihre neu erstellte
TransactionDecision-Szene aus. - Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
Geben Sie in das Textfeld die folgende Syntax für Bedingungen ein, um die Erfolgsbedingungen zu prüfen:
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 Aufwärtspfeil, um sie vor
if scene.slots.status == "FINAL"zu platzieren.Aktivieren Sie die Option Aufforderungen senden und geben Sie eine einfache Aufforderung an, um dem Nutzer mitzuteilen, dass die Bestellung abgeschlossen wurde:
candidates: - first_simple: variants: - speech: >- Transaction completed! Your order $session.params.TransactionDecision.order.merchantOrderId is all set!Wählen Sie unter Übergang die Option Unterhaltung beenden aus, um sie zu beenden.
Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
Geben Sie in das Textfeld die folgende Syntax für Bedingungen 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 Aufwärtspfeil, um sie vor
if scene.slots.status == "FINAL"zu platzieren.Aktivieren Sie die Option Aufforderungen senden und geben Sie eine einfache Aufforderung an, den Nutzer über die Ablehnung der Bestellung zu informieren:
candidates: - first_simple: variants: - speech: Look like you don't want to order anything. Goodbye.Wählen Sie unter Übergang die Option Unterhaltung beenden aus, um sie zu beenden.
Wählen Sie die Bedingung
else if scene.slots.status == "FINAL"aus.Aktivieren Sie die Option Aufforderungen senden und geben Sie eine einfache Aufforderung an, dem Nutzer mitzuteilen, dass er keine Transaktion durchführen kann:
candidates: - first_simple: variants: - speech: >- Transaction failed with status $session.params.TransactionDecision.transactionDecisionWählen Sie unter Umstellung die Option Unterhaltung beenden aus, um die Unterhaltung zu beenden, wenn ein Nutzer keine Transaktionen durchführen kann.
Bestellung abschließen und Beleg senden
Wenn der Slot TransactionDecisionValue ein Ergebnis von ORDER_ACCEPTED zurückgibt, müssen Sie sofort die Verarbeitung ausführen, die zum „Bestätigen“ der Bestellung erforderlich ist, z. B. die Speicherung in Ihrer eigenen Datenbank und die Belastung des Nutzers.
Sie können die Unterhaltung mit dieser Antwort beenden, aber Sie müssen eine einfache Antwort hinzufügen, um die Unterhaltung fortzusetzen. Wenn Sie diese erste orderUpdate angeben, sieht der Nutzer eine „Minimierte Belegkarte“ zusammen mit dem Rest Ihrer Antwort. Diese Karte spiegelt den Beleg wider, den der Nutzer in seinem Bestellverlauf findet.
Während der Bestellbestätigung kann Ihr Bestellobjekt ein userVisibleOrderId enthalten. Das ist die ID, die der Nutzer für die Bestellung sieht. Sie können merchantOrderId für dieses Feld wiederverwenden.
Ein Teil des OrderUpdate-Objekts muss ein Folge-Aktionsobjekt enthalten, das sich als URL-Schaltflächen am Ende der Bestelldetails befindet, die der Nutzer in seinem Assistant-Bestellverlauf finden kann.
- Sie müssen für jede Bestellung mindestens eine
VIEW_DETAILS-Aktion angeben. Es sollte einen Deeplink zur Darstellung der Bestellung in Ihrer mobilen App oder auf Ihrer Website enthalten. - Zusätzlich zur Beleg-Karte in Ihrem Gespräch müssen Sie auch einen formalen Beleg per E-Mail senden, der alle rechtlichen Erfordernisse für eine Transaktion erfüllt.
So senden Sie ein anfängliches Bestellupdate:
- Wähle auf dem Tab Szenen deine
TransactionDecision-Szene aus. Wählen Sie unter Bedingung die Bedingung aus, mit der auf das Erfolgsergebnis
ORDER_ACCEPTEDgeprüft wird:scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"Aktivieren Sie für diese Bedingung Rufen Sie Ihren Webhook auf und geben Sie einen Namen für einen Intent-Handler wie
update_orderan.
Fügen Sie im Webhook-Code einen Intent-Handler zum Senden einer ersten Bestellaktualisierung hinzu:
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 })); });
Updates zu Bestellungen senden
Sie müssen den Nutzer während seiner gesamten Laufzeit über den Status der Bestellung informieren. Senden Sie die Updates für die Nutzerbestellung, indem Sie HTTP-PATCH-Anfragen mit dem Bestellstatus und den Details an die Orders API senden.
Asynchrone Anfragen an die Orders API einrichten
Anfragen zur Bestellaktualisierung an die Orders API sind durch ein Zugriffstoken autorisiert. Wenn Sie ein Bestellupdate an die Orders API PATCH senden möchten, laden Sie einen JSON-Dienstkontoschlüssel herunter, der mit Ihrem Actions Console-Projekt verknüpft ist, und tauschen Sie dann den Dienstkontoschlüssel gegen ein Inhabertoken aus, das an den Header Authorization der HTTP-Anfrage weitergegeben wird.
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-accountfest. - Legen Sie Rolle auf Projekt > Inhaber fest.
- Legen Sie den Schlüsseltyp auf JSON fest.
- Wählen Sie Erstellen aus.
- Ein privater JSON-Dienstkontoschlüssel wird auf Ihren lokalen Computer heruntergeladen.
In Ihrem Code zur Bestellaktualisierung können Sie Ihren Dienstschlüssel mit 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 zur API-Clientbibliothek.
Sie können auch in unserem Node.js-Beispiel auf order-update.js verweisen.
Updates zu Bestellungen 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.
Orders API-URL:
PATCH https://actions.googleapis.com/v3/orders/${orderId}
Geben Sie in Ihrer Anfrage die folgenden Header an:
"Authorization: Bearer token"durch das OAuth-Inhabertoken, für das Sie Ihren Dienstkontoschlüssel ausgetauscht haben."Content-Type: application/json".
Die PATCH-Anfrage sollte einen JSON-Textkörper im folgenden Format haben:
{ "orderUpdate": OrderUpdate }
Das OrderUpdate-Objekt besteht aus den folgenden Feldern der obersten Ebene:
updateMask: die Felder des Auftrags, den Sie aktualisieren Wenn Sie den Bestellstatus aktualisieren möchten, setzen Sie den Wert aufpurchase.status, purchase.userVisibleStatusLabel.order: Der Inhalt des Updates. Wenn Sie den Inhalt der Bestellung aktualisieren, legen Sie 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: Dieselbe ID, die Sie in IhremOrder-Objekt festgelegt haben.lastUpdateTime: Der Zeitstempel dieser Aktualisierung.purchase: ein Objekt mit folgendem Inhalt:status: Der Status der Bestellung alsPurchaseStatus, z. B. „SHIPPED“ oder „DELIVERED“.userVisibleStatusLabel: Ein für Nutzer sichtbares Label mit Details zum Bestellstatus, z. B. „Ihre Bestellung wurde versendet und ist unterwegs“.
userNotification(optional): EinuserNotification-Objekt, das auf dem Gerät des Nutzers angezeigt wird, wenn dieses Update gesendet wird. Das Hinzufügen dieses Objekts ist keine Garantie dafür, dass eine Benachrichtigung auf dem Gerät des Nutzers angezeigt wird.
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
Die status eines Auftragsupdates muss den aktuellen Status der Bestellung beschreiben. Verwenden Sie im Feld order.purchase.status der Aktualisierung einen der folgenden Werte:
CREATED– Die Bestellung wird vom Nutzer akzeptiert und aus Sicht Ihrer Aktion erstellt, erfordert aber eine manuelle Verarbeitung in Ihrem Back-End.CONFIRMED: Die Bestellung ist aktiv und wird zur Auftragsausführung verarbeitet.IN_PREPARATION– Die Bestellung wird für den Versand/die Lieferung vorbereitet, z. B. Kochen oder Verpacken eines Artikels.READY_FOR_PICKUP: Die Bestellung kann vom Empfänger abgeholt werden.DELIVERED– Die Bestellung wurde an den Empfänger geliefertOUT_OF_STOCK: Mindestens ein Teil der Bestellung ist nicht auf Lager.CHANGE_REQUESTED: Der Nutzer hat eine Änderung an der Bestellung angefordert und diese wird gerade verarbeitet.RETURNED: Die Bestellung wurde nach der Lieferung vom Nutzer zurückgegeben.REJECTED: Wenn Sie die Bestellung nicht verarbeiten, belasten oder anderweitig „aktivieren“ konnten.CANCELLED: Die Bestellung wurde vom Nutzer storniert.
Sie sollten Bestellaktualisierungen für jeden Status senden, der für Ihre Transaktion relevant ist. Wenn Ihre Transaktion beispielsweise eine manuelle Verarbeitung erfordert, um die Bestellung nach ihrer Bestellung zu protokollieren, senden Sie eine CREATED-Bestellaktualisierung, bis diese zusätzliche Verarbeitung abgeschlossen ist. Nicht jede Bestellung muss alle Werte haben.
Projekt testen
Beim Testen Ihres Projekts können Sie den Sandbox-Modus in der Aktionen-Konsole aktivieren, um Ihre Aktion zu testen, ohne eine Zahlungsmethode zu belasten. So aktivieren Sie den Sandbox-Modus:
- Klicken Sie in der Aktionen-Konsole in der Navigation auf Testen.
- Klicken Sie auf Einstellungen.
- Aktivieren Sie die Option Development Sandbox.
Für physische Transaktionen können Sie in Ihrem Beispiel auch das Feld isInSandbox auf true setzen. Diese Aktion entspricht der Einstellung des Sandbox-Modus in der Actions Console. Informationen zum Code-Snippet, das isInSandbox verwendet, finden Sie im Abschnitt Bestellaktualisierungen senden.
Fehlerbehebung
Falls während des Tests Probleme auftreten, sollten Sie unsere Schritte zur Fehlerbehebung für Transaktionen lesen.