Asynchrone Aktualisierung der Bestellung

Nachdem ein Kunde eine Essensbestellung aufgegeben hat, können Sie an den „Order with Google“-Dienst eine Nachricht zur Bestellaktualisierung senden, um uns über die Änderung zu informieren.

Hier finden Sie einige häufige Gründe für das Senden von Bestellaktualisierungen:

• Die voraussichtliche Auftragsausführungszeit für die Bestellung ist verfügbar oder ändert sich.
• Der Status einer Bestellung ändert sich.
• Die Bestellung kann nicht mehr ausgeführt werden.
• Der Preis eines in der Bestellung enthaltenen Speisekartenartikels hat sich geändert.
• Der Kunde hat eine neue Möglichkeit, seine Bestellung zu verwalten, z. B. Kundensupport oder Telefonnummer des Restaurants.
• Der Beleg für die Bestellung ist verfügbar.

In den nächsten Abschnitten wird beschrieben, wie Sie diese Szenarien mithilfe von Bestellaktualisierungen angehen können.

Status der Umstellungsreihenfolge

Eine Bestellung hat sechs mögliche Zustände. Diese Status und ihre möglichen Übergänge werden im folgenden Diagramm dargestellt:

Wenn ein Kunde zum ersten Mal eine Bestellung aufgibt, beginnt sie mit dem Status CREATED, CONFIRMED oder REJECTED. Sie können eine Nachricht zur Bestellaktualisierung senden, um den Status einer Bestellung zu aktualisieren, sofern der Statusübergang gültig ist. Der Status CREATED wird verwendet, wenn die Bestellung auf der Plattform des Partners nicht sofort bestätigt oder abgelehnt werden kann. Ein Beispiel für einen Anwendungsfall ist, wenn ein Kunde über einen Lieferaggregator bestellt. Der Aggregator erhält den Lieferdienst von Google und er sendet die Informationen an das Restaurant. Sobald das Restaurant die Verfügbarkeit der Bestellung erhalten und bestätigt hat, kann der Status CONFIRMED sein, andernfalls REJECTED.

Eine Bestellung mit dem Status CONFIRMED wird als Nächstes in den Status IN_PREPARATION verschoben. Je nachdem, ob eine Bestellung zur Abholung oder Lieferung bestellt wurde, verwenden Sie entweder den Status READY_FOR_PICKUP oder IN_TRANSIT. Wenn das Essen geliefert oder abgeholt wurde, wird der Status der Bestellung auf FULFILLED gesetzt.

Wenn Sie es Kunden ermöglichen, Bestellungen zu stornieren, können Sie den Status CANCELLED verwenden. Eine Bestellung kann im Status CREATED, CONFIRMED, IN_PREPARATION, READY_FOR_PICKUP oder IN_TRANSIT storniert werden. Je nach Ihren Stornierungsrichtlinien und dem Status der Zahlungen zum Zeitpunkt der Kündigung sollte die Bestellung über Ihren Dienst „Order with Google“ erfolgen.

Ihr „Order with Google“-Dienst muss nicht alle verfügbaren Status und Umstellungen unterstützen. Der endgültige Status der Bestellung muss aber FULFILLED, REJECTED oder CANCELLED lauten.

Geschätzte Dauer zur Auftragsausführung

Sie können Nutzern einen geschätzten Zeitraum für die Abholung ihrer Bestellung oder die Lieferung ihrer Bestellung mitteilen. Verwenden Sie das Feld estimatedFulfillmentTimeIso8601 von FoodOrderUpdateExtension, um einen geschätzten Zeitraum anzugeben, in dem die Bestellung eines Kunden zur Abholung bereitsteht oder geliefert wird.

Sende die estimatedFulfillmentTimeIso8601 zu folgenden Zeiten:

• Wenn die geschätzte Zeit verfügbar ist, idealerweise im Status CREATED oder CONFIRMED.
• Wenn sich die geschätzte Zeit ändert, z. B. wenn die geschätzte Zeit aktualisiert wird, wenn die Bestellung IN_TRANSIT ist.

Um die Erwartungen der Nutzer effektiv zu verwalten, sollten Sie in Ihren Schätzungen eher konservativ vorgehen und ein Datum und einen Zeitraum anstelle eines festen Datums und einer Uhrzeit angeben. Sie sollten nach Möglichkeit Variationen wie die Verkehrslage berücksichtigen. So können Sie beispielsweise für eine Bestellung mit einer geschätzten Lieferzeit von 13:00 Uhr eine Schätzung von 12:45 Uhr (Untergrenze) bis 13:15 Uhr (Obergrenze) senden.

Bestellverwaltungsaktionen ermöglichen

Wenn Sie ein Bestellupdate senden, können Sie Kunden Ressourcen zur Verfügung stellen, die sie bei der Verwaltung ihrer Bestellung in Form von OrderManagementAction unterstützen. Nachdem ein Kunde eine Bestellung aufgegeben hat, muss er sich möglicherweise an Sie oder das Restaurant wenden, in dem die Bestellung ausgeführt wird, um den Fortschritt zu verfolgen, Änderungen vorzunehmen oder die Bestellung zu stornieren.

Mit OrderManagementAction können Kunden direkt von ihrem Gerät aus eine URL per E-Mail, Anruf oder durch einen Link zu einer URL aufrufen. Verwenden Sie in OrderManagementAction dieselben Informationen wie in der E-Mail-Bestellbestätigung, die Sie an den Nutzer senden.

Zu den Bestellverwaltungsaktionen gehören:

• CUSTOMER_SERVICE: Bieten Sie Kunden die Möglichkeit, den Kundenservice zu kontaktieren. Dieser Typ von Verwaltungsaktion ist für Aktualisierungen von Bestellungen erforderlich.
• EMAIL: Kunden werden aufgefordert, eine E-Mail an die angegebene E-Mail-Adresse zu senden.
• CALL: Geben Sie Nutzern die Möglichkeit, die angegebene Telefonnummer anzurufen.
• VIEW_DETAIL: Kunden werden aufgefordert, die Details ihrer Bestellung anzusehen.

Jede Bestellaktualisierung muss mindestens eine Bestellverwaltungsaktion enthalten. Die bereitgestellten Aktionen zur Bestellverwaltung können jedoch je nach Status der Bestellung variieren. Wenn eine Bestellung beispielsweise den Status CONFIRMED hat, kann die Aktion CUSTOMER_SERVICE auf die Telefonnummer Ihres Kundenservice verweisen. Wenn dieser Bestellstatus zu IN_TRANSIT geändert wird, kann die Aktion CUSTOMER_SERVICE auf die Telefonnummer des Restaurants für die Auftragsausführung verweisen.

Bestellaktualisierungen werden gesendet

Mit dem Nachrichtentyp AsyncOrderUpdateRequestMessage senden Sie eine Bestellung an den „Order with Google“-Dienst. Google antwortet mit einer AsyncOrderUpdateResponseMessage. Wenn Sie beispielsweise einen Kunden darüber informieren möchten, dass seine Bestellung gültig und akzeptiert wurde, können Sie eine AsyncOrderUpdateRequestMessage senden, um den Status der Bestellung mit dem Label Accepted by restaurant in CONFIRMED zu ändern.

Nachricht für die Bestellaktualisierung festlegen

Wenn Sie eine AsyncOrderUpdateRequestMessage an Google senden, müssen Sie im Feld OrderUpdate Informationen zum Status der Bestellung angeben.

Hinweis :Die actionOrderId ist die eindeutige ID, mit der die zu aktualisierende Bestellung identifiziert wird. Die actionOrderId muss mit dem Wert übereinstimmen, den Sie in der Aktion zum Senden der Bestellung zurückgegeben haben. Wenn die Bestellung mit isInSandbox auf „true“ erstellt wurde, müssen Sie auch isInSandbox in der AsyncOrderUpdateRequestMessage mit „true“ angeben.

Die folgenden Beispiele zeigen ein AsyncOrderUpdateRequestMessage-Beispiel für jeden Bestellstatus:

BESTÄTIGT

Dieses Beispiel zeigt eine Anfrage zur Aktualisierung einer Bestellung, mit der der Nutzer darüber informiert wird, dass die Bestellung mit einem Beleg und einer voraussichtlichen Lieferdauer bestätigt wurde.

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "CONFIRMED",
        "label": "Provider confirmed"
      },
      "receipt": {
        "userVisibleOrderId": "userVisibleId1234"
      },
      "updateTime": "2017-07-17T12:00:00Z",
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
      }
    }
  }
}
    

ABGELEHNT

Dieses Beispiel zeigt eine Anfrage zur Aktualisierung einer Bestellreihenfolge, die den Nutzer darüber informiert, dass die Bestellung mit einem Ablehnungsgrund abgelehnt wurde.

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "REJECTED",
        "label": "Order rejected"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "rejectionInfo": {
        "type": "UNKNOWN",
        "reason": "Sorry, the restaurant cannot take your order right now."
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ],
      "infoExtension": {
      "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
      "foodOrderErrors": [
        {
        "error": "NO_CAPACITY",
        "description": "Sorry, the restaurant cannot take your order right now."
        }
      ]
      }
    }
  }
}
    

CANCELLED

Dieses Beispiel zeigt eine Anfrage zur Aktualisierung einer Bestellung, in der der Nutzer darüber informiert wird, dass die Bestellung mit einem Stornierungsgrund storniert wurde.

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "CANCELLED",
        "label": "Order cancelled"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "cancellationInfo": {
        "reason": "Customer requested"
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ]
    }
  }
}
    

IN_PREPARATION

Dieses Beispiel zeigt eine Anfrage zur Aktualisierung einer Bestellreihenfolge, die den Nutzer darüber informiert, dass das Essen gerade zubereitet wird.

{
  "isInSandbox":true,
  "customPushMessage":{
    "orderUpdate":{
      "actionOrderId":"sample_action_order_id",
      "orderState":{
        "state":"IN_PREPARATION",
        "label":"Order is being prepared"
      },
      "receipt": {
        "userVisibleOrderId": "userVisibleId1234"
      },
      "updateTime":"2018-04-15T11:30:00Z",
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ],
      "infoExtension":{
        "@type":"type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "estimatedFulfillmentTimeIso8601":"PT20M"
      }
    }
  }
}
    

Bereit für die Abholung

Dieses Beispiel zeigt eine Anfrage zur Aktualisierung einer Bestellreihenfolge, die den Nutzer darüber informiert, dass die Bestellung zur Abholung bereitsteht.

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "READY_FOR_PICKUP",
        "label": "Order is ready for pickup"
      },
      "receipt": {
        "userVisibleOrderId": "userVisibleId1234"
      },
      "updateTime": "2018-04-15T12:00:00Z",
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "estimatedFulfillmentTimeIso8601": "PT20M"
      }
    }
  }
}
    

IN_TRANSIT

Dieses Beispiel zeigt eine Anfrage zur Aktualisierung einer Bestellreihenfolge, die den Nutzer darüber informiert, dass die Bestellung unterwegs ist und eine voraussichtliche Lieferdauer angibt.

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "IN_TRANSIT",
        "label": "Order is on the way"
      },
      "inTransitInfo": {
        "updatedTime": "2017-07-17T12:00:00Z"
      },
      "updateTime": "2017-07-17T12:00:00Z",
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "estimatedFulfillmentTimeIso8601": "PT20M"
      }
    }
  }
}
  

AUSGEFÜHRT

Dieses Beispiel zeigt eine Anfrage zur Aktualisierung einer Bestellbenachrichtigung, die den Nutzer darüber informiert, dass die Bestellung abgeholt oder geliefert wird:

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
      "state": "FULFILLED",
      "label": "Order delivered"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "fulfillmentInfo": {
        "deliveryTime": "2017-05-10T02:30:00.000Z"
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ]
    }
  }
}
    

Weitere Beispiele für Anfragen zur Bestellaktualisierung in verschiedenen Anwendungsfällen finden Sie unter Erweiterte Bestellaktualisierungen implementieren.

Autorisierungstoken generieren und Nachricht senden

Für Aktualisierungen von Bestellungen ist ein Autorisierungstoken erforderlich, damit der „Order with Google“-Dienst prüfen kann, ob die Nachricht von deinem „Order with Google“-Webdienst stammt.

So implementieren Sie Bestellaktualisierungen für Ihr Projekt:

1. Generieren Sie ein Autorisierungstoken, indem Sie die folgenden Schritte ausführen:
   1. Verwenden Sie die Google-Authentifizierungsbibliothek, um die Anmeldedaten aus Ihrer Dienstkontodatei zu lesen.
   2. Fordern Sie ein Token mit dem folgenden API-Bereich an: https://www.googleapis.com/auth/actions.fulfillment.conversation
2. Verwenden Sie dieses Token, um eine authentifizierte HTTP POST-Anfrage an den folgenden Endpunkt zu senden: https://actions.googleapis.com/v2/conversations:send
3. Legen Sie den Content-Type-Header auf application/json als Teil Ihrer Anfrage fest.

Wichtig: Legen Sie beim Senden von Bestellaktualisierungen für Bestellungen über die Vorschauumgebung das Feld isInSandbox von AsyncOrderUpdateRequestMessage auf true fest.

Die folgenden Beispiele zeigen, wie Bestellaktualisierungen implementiert werden:

Node.js

Dieser Code verwendet die Google-Authentifizierungsbibliothek für Node.js.

const {auth} = require('google-auth-library')
const request = require('request');
// The service account client secret file downloaded from the Google Cloud Console
const serviceAccountJson = require('./service-account.json')
// order-update.json is a file that contains the payload
const jsonBody = require('./order-update.json')

/**
 * Get the authorization token using a service account.
 */
async function getAuthToken() {
  let client = auth.fromJSON(serviceAccountJson)
  client.scopes = ['https://www.googleapis.com/auth/actions.fulfillment.conversation']
  const tokens = await client.authorize()
  return tokens.access_token;
}

/**
 * Send an order update request
 */
async function sendOrderUpdate() {
  const token = await getAuthToken()
  request.post({
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    url: 'https://actions.googleapis.com/v2/conversations:send',
    body: jsonBody,
    json: true
  },
  (err, res, body) => {
    if (err) { return console.log(err); }
    console.log(`Response: ${JSON.stringify(res)}`)
  })
}
    

Python

Dieser Code verwendet die Google-Authentifizierungsbibliothek für Python.

from google.oauth2 import service_account
from google.auth.transport.requests import AuthorizedSession
import json

# service-account.json is the service account client secret file downloaded from the
# Google Cloud Console
credentials = service_account.Credentials.from_service_account_file(
    'service-account.json')

scoped_credentials = credentials.with_scopes(
    ['https://www.googleapis.com/auth/actions.fulfillment.conversation'])

authed_session = AuthorizedSession(scoped_credentials)

# order-update.json is a file that contains the payload
json_payload=json.load(open('order-update.json'))

response = authed_session.post(
    'https://actions.googleapis.com/v2/conversations:send',
    json=json_payload)
    

Java

Dieser Code verwendet die Google-Authentifizierungsbibliothek für Java.

/**
 * Get the authorization token using a service account.
 */
private static String getAuthToken() {
  InputStream serviceAccountFile = Example.class.getClassLoader().getResourceAsStream("service-account.json");
  ServiceAccountCredentials.Builder credentialsSimpleBuilder =
      ServiceAccountCredentials.fromStream(serviceAccountFile).toBuilder();
  credentialsSimpleBuilder.setScopes(ImmutableList.of("https://www.googleapis.com/auth/actions.fulfillment.conversation"));
  AccessToken accessToken = credentialsSimpleBuilder.build().refreshAccessToken();
  return accessToken.getTokenValue();
}

/**
 * Send an order update request
 */
public void sendOrderUpdate() {
  String authToken = getAuthToken();
  // Execute POST request
  executePostRequest("https://actions.googleapis.com/v2/conversations:send",
      authToken, "update_order_example.json",);
}
    

Bei erfolgreichen Bestellaktualisierungen ohne Fehler gibt Google eine HTTP 200-Antwort mit leerer Nutzlast zurück. Wenn ein Problem auftritt, z. B. wenn die Aktualisierung fehlerhaft ist, gibt Google einen Fehler zurück.