Vom Händler verwaltete Zahlungen für physische Transaktionen

In diesem Leitfaden wird Schritt für Schritt erklärt, wie du ein Actions-Projekt entwickelst, das Transaktionen für physische Waren mit Zahlungsmethoden umfasst, die über deine Website verwaltet werden.

Transaktionsablauf

Wenn in Ihrem Actions-Projekt physische Transaktionen mit vom Händler verwalteten Zahlungen verarbeitet werden, wird der folgende Ablauf verwendet:

  1. Nutzerkonto verknüpfen: Damit der Nutzer eine bei Ihrem Dienst gespeicherte Zahlungsmethode verwenden kann, verwenden Sie die Kontoverknüpfung, um sein Google-Konto mit seinem Konto bei Ihrem Dienst zu verknüpfen.
  2. Informationen erfassen (optional): Je nach Art der Transaktion möchten Sie möglicherweise zu Beginn der Unterhaltung die folgenden Informationen vom Nutzer einholen:
    1. Transaktionsanforderungen validieren: Überprüfen Sie zu Beginn des Transaktionsabschnitts der Konversation, ob der Nutzer die Anforderungen für eine Transaktion erfüllt, z. B. ob er vor dem Erstellen des Einkaufswagens Zahlungsinformationen richtig konfiguriert und verfügbar hat.
    2. Lieferadresse anfordern: Wenn für die Transaktion eine Lieferadresse erforderlich ist, fordern Sie eine vom Nutzer an.
  3. Bestellung zusammenstellen: Gehe mit dem Nutzer durch einen „Wagenbau“, bei dem er die Artikel auswählt, die er kaufen möchte.
  4. 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.
  5. 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.
  6. 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
Katar
Russland
Singapur
Schweiz
Thailand
Türkei
Vereinigtes Königreich
USA

Ihr Projekt erstellen

Ein Beispiel für eine transaktionale Unterhaltung finden Sie im Beispiel für Node.js-Transaktionen.

Projekt einrichten

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:

  1. Erstellen Sie ein neues Projekt oder importieren Sie ein vorhandenes Projekt.
  2. Gehen Sie zu Bereitstellen > Verzeichnisinformationen.
  3. Klicke unter Zusätzliche Informationen > Transaktionen auf das Kästchen neben "Verwenden deine Aktionen die Transactions API, um Transaktionen mit physischen Waren durchzuführen?".

Wenn Sie Ihre eigene Zahlungsmethode verwenden, um dem Nutzer Kosten in Rechnung zu stellen, empfehlen wir, sein Google-Konto mit einem Konto mit Ihrem eigenen Dienst zu verknüpfen, um die dort gespeicherten Zahlungsmethoden abzurufen, zu präsentieren und zu belasten.

Die Sprach-Benutzeroberfläche für den Authentifizierungsablauf entwerfen

Prüfe, ob der Nutzer bestätigt ist, und starte den Vorgang zur Kontoverknüpfung

  1. Öffnen Sie Ihr Actions Builder-Projekt in der Actions Console.
  2. Erstelle eine neue Szene, um die Kontoverknüpfung in deiner Aktion zu starten:
    1. Klicken Sie auf Szenen.
    2. Klicken Sie auf das Symbol Hinzufügen (+), um eine neue Szene hinzuzufügen.
  3. Klicken Sie in der neu erstellten Szene auf das Symbol zum Hinzufügen von Bedingungen.
  4. Fügen Sie eine Bedingung hinzu, die prüft, ob der mit der Unterhaltung verknüpfte Nutzer ein bestätigter Nutzer ist. Wenn die Prüfung fehlschlägt, kann deine Aktion während der Unterhaltung keine Kontoverknüpfung vornehmen und sollte auf Funktionen zugreifen, für die keine Kontoverknüpfung erforderlich ist.
    1. Geben Sie im Feld Enter new expression unter Bedingung die folgende Logik ein: user.verificationStatus != "VERIFIED"
    2. Wählen Sie unter Übergang eine Szene aus, für die keine Kontoverknüpfung erforderlich ist, oder eine Szene, die der Einstiegspunkt für die Funktion nur für Gäste ist.

  1. Klicken Sie unter Conditions (Bedingungen) auf das Symbol zum Hinzufügen .
  2. Fügen Sie eine Bedingung hinzu, um einen Kontoverknüpfungsvorgang auszulösen, wenn der Nutzer keine verknüpfte Identität hat.
    1. Geben Sie im Feld Enter new expression unter Bedingung die folgende Logik ein: user.verificationStatus == "VERIFIED"
    2. Wählen Sie unter Umstellung die Systemszene Kontoverknüpfung aus.
    3. Klicken Sie auf Speichern.

Nach dem Speichern wird dem Projekt eine neue Systemszene zur Kontoverknüpfung mit dem Namen <SceneName>_AccountLinking hinzugefügt.

Szene für die Kontoverknüpfung anpassen

  1. Wählen Sie unter Szenen die Systemszene für die Kontoverknüpfung aus.
  2. Klicke auf Prompt senden und füge einen kurzen Satz hinzu, um dem Nutzer zu beschreiben, warum die Aktion auf seine Identität zugreifen muss (z. B. „Zum Speichern deiner Einstellungen“).
  3. Klicken Sie auf Speichern.

  1. Klicken Sie unter Bedingungen auf Wenn der Nutzer die Kontoverknüpfung erfolgreich abschließt.
  2. Legen Sie fest, wie der Ablauf ausgeführt werden soll, wenn der Nutzer der Verknüpfung seines Kontos zustimmt. Rufen Sie beispielsweise den Webhook auf, um die erforderliche benutzerdefinierte Geschäftslogik zu verarbeiten und zurück zur ursprünglichen Szene zu wechseln.
  3. Klicken Sie auf Speichern.

  1. Klicken Sie unter Bedingungen auf Wenn der Nutzer die Kontoverknüpfung aufhebt oder ablehnt.
  2. Legen Sie fest, wie der Ablauf ausgeführt werden soll, wenn der Nutzer der Verknüpfung seines Kontos nicht zustimmt. Sie können beispielsweise eine Bestätigungsnachricht senden und zu Szenen weiterleiten, die Funktionen bieten, für die keine Kontoverknüpfung erforderlich ist.
  3. Klicken Sie auf Speichern.

  1. Klicken Sie unter Bedingungen auf Bei System- oder Netzwerkfehlern.
  2. Legen Sie fest, wie der Ablauf ausgeführt werden soll, wenn der Kontoverknüpfungsvorgang aufgrund von System- oder Netzwerkfehlern nicht abgeschlossen werden kann. Sie können beispielsweise eine Bestätigungsnachricht senden und zu Szenen weiterleiten, die Funktionen bieten, für die keine Kontoverknüpfung erforderlich ist.
  3. Klicken Sie auf Speichern.

Informationen erfassen (optional)

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öchten Sie Schuhe bestellen oder Ihren 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
  1. Fügen Sie auf dem Tab „Szenen“ eine neue Szene mit dem Namen TransactionRequirementsCheck hinzu.
  2. Klicken Sie unter Slot-Füllung auf +, um eine neue Anzeigenfläche hinzuzufügen.
  3. Wählen Sie unter Typ auswählen actions.type.TransactionRequirementsCheckResult als Slottyp aus.
  4. Geben Sie der Anzeigenfläche den Namen TransactionRequirementsCheck im Feld für den Slotnamen.
  5. Klicken Sie das Kästchen Rückschreibe für Slotwert anpassen an (standardmäßig aktiviert).
  6. 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

  1. Wählen Sie auf dem Tab Szenen die neu erstellte Szene TransactionRequirementsCheck aus.
  2. Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
  3. 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"
    
  4. 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.

  5. 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.
    
  6. Wählen Sie unter Übergang eine andere Szene aus, damit der Nutzer die Unterhaltung fortsetzen und mit der Transaktion fortfahren kann.

  7. Wählen Sie die Bedingung else if scene.slots.status == "FINAL" aus.

  8. 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.
    
  9. Wählen Sie unter Umstellung die Option Unterhaltung beenden aus, um die Unterhaltung zu beenden, wenn ein Nutzer keine Transaktionen vornehmen kann.

Lieferadresse anfordern (optional)

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

  1. Fügen Sie auf dem Tab Szenen eine neue Szene mit dem Namen DeliveryAddress hinzu.
  2. Klicken Sie unter Slot-Füllung auf +, um eine neue Anzeigenfläche hinzuzufügen.
  3. Wählen Sie unter Typ auswählen actions.type.DeliveryAddressValue als Slottyp aus.
  4. Geben Sie der Anzeigenfläche den Namen TransactionDeliveryAddress im Feld für den Slotnamen.
  5. Klicken Sie das Kästchen Rückschreibe für Slotwert anpassen an (standardmäßig aktiviert).
  6. 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:

  1. Wählen Sie auf dem Tab Szenen die neu erstellte Szene DeliveryAddress aus.
  2. Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
  3. 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"
    
  4. 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.

  5. 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
    
  6. Wählen Sie unter Übergang eine andere Szene aus, damit der Nutzer die Unterhaltung fortsetzen kann.

  7. Wählen Sie die Bedingung else if scene.slots.status == "FINAL" aus.

  8. 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.
    
  9. 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 eine hochwertige Montage von Einkaufswagen finden Sie in den Richtlinien für das Transaktionsdesign.

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ätigt
  • transactionMerchant: Informationen zum Händler, der die Bestellung durchgeführt hat.
  • contents: Der tatsächliche Inhalt des Auftrags, der als lineItems 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.

Im Folgenden findest du Bestell- und Präsentationsoptionen für Bestellungen, für die eine Lieferadresse erforderlich ist, einschließlich der E-Mail-Adresse des Nutzers auf der Bestellbestätigungskarte:

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

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

Zahlungsparameter erstellen

Das paymentParameters-Objekt enthält ein merchantPaymentOption-Objekt mit Feldern, die die Zahlungsmethode des Nutzers für seine Bestellung beschreiben. Im Folgenden finden Sie ein Beispiel für Zahlungsparameter mit einer Visa-Kreditkarte:

const paymentParamenters = {
      'merchantPaymentOption': {
        'defaultMerchantPaymentMethodId': '12345678',
        'managePaymentMethodUrl': 'https://example.com/managePayment',
        'merchantPaymentMethod': [{
          'paymentMethodDisplayInfo': {
            'paymentMethodDisplayName': 'VISA **** 1234',
            'paymentType': 'PAYMENT_CARD'
          },
          'paymentMethodGroup': 'Payment method group',
          'paymentMethodId': '12345678',
          'paymentMethodStatus': {
            'status': 'STATUS_OK',
            'statusMessage': 'Status message'
          }
        }]
      }
    };

Bestelldaten im Sitzungsparameter speichern

Speichern Sie die Bestelldaten in der Auftragsausführung in einem session-Parameter. 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

  1. Fügen Sie auf dem Tab Szenen eine neue Szene mit dem Namen TransactionDecision hinzu.
  2. Klicken Sie unter Slot-Füllung auf +, um eine neue Anzeigenfläche hinzuzufügen.
  3. Wählen Sie unter Typ auswählen actions.type.TransactionDecisionValue als Slottyp aus.
  4. Geben Sie der Anzeigenfläche den Namen TransactionDecision im Feld für den Slotnamen.
  5. Klicken Sie das Kästchen Rückschreibe für Slotwert anpassen an (standardmäßig aktiviert).
  6. Wählen Sie unter Slot konfigurieren im Drop-down-Menü die Option Sitzungsparameter verwenden aus.
  7. Geben Sie unter Slot konfigurieren den Namen des Sitzungsparameters ein,der zum Speichern der Bestellung im Textfeld verwendet wird (z.B. $session.params.order).
  8. 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:

  1. Wählen Sie auf dem Tab Szenen die neu erstellte Szene TransactionDecision aus.
  2. Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.
  3. 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"
    
  4. 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.

  5. 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!
    
  6. Wählen Sie unter Umstellung die Option Unterhaltung beenden aus.

  7. Klicken Sie unter Bedingung auf +, um eine neue Bedingung hinzuzufügen.

  8. 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"
    
  9. 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.

  10. 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.
    
  11. Wählen Sie unter Umstellung die Option Unterhaltung beenden aus.

  12. Wählen Sie die Bedingung else if scene.slots.status == "FINAL" aus.

  13. 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
    
  14. 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:

  1. Wähle auf dem Tab Szenen deine TransactionDecision-Szene aus.
  2. 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"
    
  3. Aktivieren Sie für diese Bedingung Webhook aufrufen und geben Sie einen Intent-Handler-Namen wie update_order an.

  4. 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:

  1. Gehen Sie in der Google Cloud Console zu Menü ⋮ > APIs und Dienste > Anmeldedaten > Anmeldedaten erstellen > Dienstkontoschlüssel.
  2. Wählen Sie unter Dienstkonto die Option Neues Dienstkonto aus.
  3. Legen Sie das Dienstkonto auf service-account fest.
  4. Stellen Sie die Rolle auf Projekt > Inhaber ein.
  5. Legen Sie den Schlüsseltyp auf JSON fest.
  6. Wählen Sie Erstellen aus.
  7. 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 auf purchase.status, purchase.userVisibleStatusLabel fest.
  • order: Der Inhalt des Updates. Wenn du den Inhalt der Bestellung aktualisierst, lege den Wert auf das aktualisierte Order-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 im Order-Objekt festgelegt haben.
    • lastUpdateTime: Der Zeitstempel dieser Aktualisierung.
    • purchase: ein Objekt, das Folgendes enthält:
      • status: Der Status der Bestellung als PurchaseStatus, 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) – Ein userNotification-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 zugestellt
  • OUT_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:

  1. Klicken Sie in der Actions Console im Navigationsbereich auf Test.
  2. Klicke auf Einstellungen.
  3. 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.