Pembaruan urutan asinkron

Setelah pelanggan mengirimkan pesanan makanan, Anda dapat mengirimkan pesan pembaruan pesanan ke layanan Pesan dengan Google untuk memberi tahu kami tentang perubahan tersebut.

Berikut adalah beberapa alasan umum untuk mengirim pembaruan pesanan:

• Perkiraan waktu pemenuhan pesanan tersedia atau berubah.
• Status pesanan akan berubah.
• Pesanan tidak dapat lagi dipenuhi.
• Harga item menu yang disertakan dalam pesanan berubah.
• Pelanggan memiliki cara baru untuk mengelola pesanan, seperti dukungan pelanggan atau nomor telepon restoran.
• Tanda terima untuk pesanan telah tersedia.

Bagian berikutnya memberikan detail tentang cara mengatasi berbagai skenario ini menggunakan update pesanan.

Status pesanan transisi

Pesanan memiliki enam kemungkinan status. Status ini dan kemungkinan transisinya diuraikan dalam diagram berikut:

Saat pelanggan pertama kali mengirimkan pesanan, pesanan dimulai dengan status CREATED, CONFIRMED, atau REJECTED. Anda dapat mengirim pesan pembaruan pesanan untuk memperbarui status pesanan, selama transisi status valid. Status CREATED digunakan saat platform partner tidak dapat segera mengonfirmasi atau menolak pesanan. Contoh kasus penggunaannya adalah saat pelanggan memesan melalui agregator penayangan. Agregator pengiriman menerima pengiriman dari Google, dan agregator mengirimkan informasi ke restoran. Setelah restoran menerima dan mengonfirmasi ketersediaan pesanan, status sekarang menjadi CONFIRMED, atau REJECTED.

Pesanan dalam status CONFIRMED berikutnya dipindahkan ke status IN_PREPARATION. Bergantung pada apakah pesanan tersebut untuk pesan ambil atau antar, selanjutnya gunakan status READY_FOR_PICKUP atau IN_TRANSIT. Jika makanan telah dikirim atau diambil, pesanan akan disetel ke status FULFILLED.

Jika Anda mengizinkan pelanggan untuk membatalkan pesanan, Anda dapat menggunakan status CANCELLED. Pesanan dapat dibatalkan saat berada dalam status CREATED, CONFIRMED, IN_PREPARATION, READY_FOR_PICKUP, atau IN_TRANSIT. Layanan Pesan dengan Google Anda harus memberikan pengembalian dana bergantung pada kebijakan pembatalan Anda dan status pembayaran pada saat pembatalan.

Layanan Pesan dengan Google Anda tidak harus mendukung semua status dan transisi yang tersedia. Namun, status akhir pesanan harus FULFILLED, REJECTED, atau CANCELLED.

Memberikan perkiraan waktu pemenuhan

Anda dapat memberi pengguna perkiraan rentang waktu kapan pesanan mereka akan siap diambil (atau dikirim). Gunakan kolom estimatedFulfillmentTimeIso8601 pada FoodOrderUpdateExtension untuk memberikan perkiraan rentang waktu saat pesanan pelanggan siap diambil atau dikirim.

Kirim estimatedFulfillmentTimeIso8601 pada saat berikut:

• Saat perkiraan waktu tersedia, idealnya dalam status CREATED atau CONFIRMED dalam urutan.
• Saat perkiraan waktu berubah, misalnya memperbarui perkiraan waktu agar lebih akurat jika pesanannya IN_TRANSIT.

Untuk mengelola ekspektasi pengguna secara efektif, jadilah konservatif dalam perkiraan Anda dan berikan rentang tanggal dan waktu, bukan tanggal dan waktu yang tetap. Anda harus memperhitungkan variasi seperti kondisi lalu lintas jika memungkinkan. Misalnya, Anda dapat mengirim perkiraan pukul 12.45 (batas bawah) hingga pukul 13.15 (batas atas) untuk pesanan dengan estimasi waktu pengiriman pukul 13.00.

Menyediakan tindakan pengelolaan pesanan

Saat mengirim pembaruan pesanan, Anda dapat memberikan resource kepada pelanggan yang membantu mereka mengelola pesanan dalam bentuk OrderManagementAction. Setelah pelanggan melakukan pemesanan, mereka mungkin perlu menghubungi Anda atau restoran yang memenuhi pesanan untuk melacak progres, melakukan perubahan, atau membatalkan pesanan mereka.

OrderManagementAction memungkinkan pelanggan mengirim email, menelepon, atau menautkan ke URL langsung dari perangkat mereka. Gunakan informasi yang sama di OrderManagementAction seperti dalam konfirmasi pesanan email yang Anda kirim kepada pengguna.

Tindakan pengelolaan pesanan mencakup jenis berikut:

• CUSTOMER_SERVICE: Berikan tindakan kepada pelanggan untuk menghubungi layanan pelanggan. Jenis tindakan pengelolaan ini diperlukan untuk pembaruan pesanan.
• EMAIL: Berikan tindakan kepada pelanggan untuk mengirim email ke alamat email yang diberikan.
• CALL: Memberikan tindakan kepada pelanggan untuk menelepon nomor telepon yang diberikan.
• VIEW_DETAIL: Memberikan tindakan kepada pelanggan untuk melihat detail pesanan mereka.

Setiap pembaruan pesanan harus berisi setidaknya satu tindakan pengelolaan pesanan. Namun, tindakan pengelolaan pesanan yang diberikan dapat bervariasi berdasarkan status pesanan. Misalnya, jika pesanan berstatus CONFIRMED, tindakan CUSTOMER_SERVICE dapat mengarah ke nomor telepon layanan pelanggan Anda. Saat status pesanan tersebut diperbarui menjadi IN_TRANSIT, tindakan CUSTOMER_SERVICE dapat mengarah ke nomor telepon restoran yang memenuhi syarat.

Mengirim pembaruan pesanan

Anda menggunakan jenis pesan AsyncOrderUpdateRequestMessage untuk mengirim pembaruan pesanan ke layanan Pesan dengan Google. Google akan merespons dengan AsyncOrderUpdateResponseMessage. Misalnya, jika Anda ingin memberi tahu pelanggan bahwa pesanan mereka valid dan diterima, Anda dapat mengirim AsyncOrderUpdateRequestMessage untuk mengubah status pesanan menjadi CONFIRMED dengan label Accepted by restaurant.

Menyetel pesan pembaruan pesanan

Saat mengirimkan AsyncOrderUpdateRequestMessage ke Google, Anda harus menyertakan informasi tentang status pesanan menggunakan kolom OrderUpdate.

Catatan: actionOrderId adalah ID unik untuk mengidentifikasi pesanan yang akan diperbarui. actionOrderId harus sama dengan nilai yang Anda tampilkan dalam tindakan pesanan yang dikirim. Jika pesanan dibuat dengan isInSandbox yang disetel ke benar (true), Anda juga harus menyertakan isInSandbox yang ditetapkan ke true di AsyncOrderUpdateRequestMessage.

Contoh berikut menunjukkan contoh AsyncOrderUpdateRequestMessage untuk setiap status pesanan:

DIKONFIRMASI

Contoh ini menunjukkan contoh permintaan pembaruan pesanan yang memberi tahu pengguna bahwa pesanan telah dikonfirmasi dengan tanda terima dan perkiraan waktu pengiriman.

{
  "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"
      }
    }
  }
}
    

DITOLAK

Contoh ini menunjukkan contoh permintaan pembaruan pesanan yang memberi tahu pengguna bahwa pesanan ditolak dengan alasan penolakan.

{
  "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 (DIBATALKAN)

Contoh ini menunjukkan contoh permintaan pembaruan pesanan yang memberi tahu pengguna bahwa pesanan dibatalkan dengan alasan pembatalan.

{
  "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]"
            }
          }
        }
      ]
    }
  }
}
    

PERSIAPAN

Contoh ini menunjukkan contoh permintaan pembaruan pesanan yang memberi tahu pengguna bahwa makanan saat ini sedang disiapkan.

{
  "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"
      }
    }
  }
}
    

SIAP_UNDUH

Contoh ini menunjukkan contoh permintaan pembaruan pesanan yang memberi tahu pengguna bahwa makanan siap diambil.

{
  "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"
      }
    }
  }
}
    

DALAM CHANNEL

Contoh ini menunjukkan contoh permintaan pembaruan pesanan yang memberi tahu pengguna bahwa pesanan sedang dalam pengiriman dengan perkiraan waktu pengiriman.

{
  "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"
      }
    }
  }
}
  

DIPUBLIKASIKAN

Contoh ini menunjukkan contoh permintaan pembaruan pesanan yang memberi tahu pengguna bahwa pesanan telah diambil atau dikirim:

{
  "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]"
            }
          }
        }
      ]
    }
  }
}
    

Untuk contoh selengkapnya tentang permintaan pembaruan pesanan dalam berbagai kasus penggunaan, baca Menerapkan pembaruan pesanan lanjutan.

Membuat token otorisasi dan mengirim pesan

Pembaruan pesanan memerlukan token otorisasi agar layanan Pesan dengan Google dapat memverifikasi bahwa pesan tersebut berasal dari layanan web Pesan dengan Google Anda.

Untuk menerapkan update pesanan untuk project Anda, ikuti langkah-langkah berikut:

1. Buat token otorisasi dengan mengikuti langkah-langkah berikut:
   1. Gunakan Library Google Auth untuk membaca kredensial dari file akun layanan Anda.
   2. Minta token menggunakan cakupan API berikut: https://www.googleapis.com/auth/actions.fulfillment.conversation
2. Gunakan token ini untuk mengirim permintaan HTTP POST yang diautentikasi ke endpoint berikut: https://actions.googleapis.com/v2/conversations:send
3. Tetapkan header Content-Type ke application/json sebagai bagian dari permintaan Anda.

Penting: Saat mengirim pembaruan pesanan untuk pesanan yang dilakukan menggunakan lingkungan Pratinjau, tetapkan kolom isInSandbox dari AsyncOrderUpdateRequestMessage ke true.

Contoh berikut menunjukkan cara menerapkan pembaruan pesanan:

Node.js

Kode ini menggunakan library autentikasi Google untuk 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

Kode ini menggunakan library autentikasi Google untuk 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

Kode ini menggunakan library autentikasi Google untuk 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",);
}
    

Agar pembaruan pesanan berhasil tanpa error, Google akan menampilkan respons HTTP 200 dengan payload kosong. Jika ada masalah, seperti perubahan format, Google akan menampilkan error.