Bu sayfa, Cloud Translation API ile çevrilmiştir.

Satıcı tarafından yönetilen ödemelerle fiziksel işlem oluşturun

Bu kılavuzda, siteniz tarafından yönetilen ödeme yöntemlerini kullanarak fiziksel ürünlerle ilgili işlemleri içeren bir Actions projesi geliştirme süreci açıklanmaktadır.

İşlem akışı

Actions projeniz, satıcı tarafından yönetilen ödemeleri kullanarak fiziksel işlemleri işlediğinde aşağıdaki akış kullanılır:

Kullanıcının hesabını bağla: Kullanıcının hizmetinize kaydettiği bir ödeme yöntemini kullanabilmesi için Hesap bağlamayı kullanarak Google hesabını hizmetinizdeki hesapla ilişkilendirin.
Bilgi toplama (isteğe bağlı) - İşleminizin yapısına bağlı olarak, görüşmenin başında kullanıcıdan aşağıdaki bilgileri toplamak isteyebilirsiniz:
1. İşlem şartlarını doğrulama - Görüşmenin işlem bölümünün başında, kullanıcının alışveriş sepeti oluşturmadan önce ödeme bilgilerinin doğru şekilde yapılandırılmış ve kullanılabilir olmasını sağlama gibi bir işlem gereksinimlerini karşıladığını doğrulayın.
2. Teslimat adresi isteme: İşlem için teslimat adresi gerekiyorsa kullanıcıdan bir adres alın.
Siparişi verin: Kullanıcıya satın almak istedikleri öğeleri seçtikleri "alışveriş sepetini" sunun.
Siparişi önerin: Alışveriş sepeti tamamlandıktan sonra, siparişin doğru olduğunu onaylaması için siparişi kullanıcıya önerin. Sipariş onaylanırsa sipariş ayrıntılarını ve ödeme jetonunu içeren bir yanıt alırsınız.
Siparişi kesinleştirin ve makbuz gönderin - Sipariş onaylandıktan sonra envanter takibinizi veya diğer sipariş karşılama hizmetlerini güncelleyin, ardından kullanıcıya bir makbuz gönderin.
Sipariş güncellemeleri gönderme - Sipariş karşılama ömrü boyunca, Siparişler API'sine PATCH istekleri göndererek kullanıcıya sipariş güncellemelerini verin.

Kısıtlamalar ve inceleme kuralları

İşlem içeren işlemler için ek politikaların geçerli olduğunu unutmayın. Actions on Actions'ı incelememiz altı haftaya kadar sürebilir. Bu nedenle, yayın planınızı planlarken bu süreyi de hesaba katın. İnceleme sürecini kolaylaştırmak için İşleminizi incelemeye göndermeden önce işlemlere ilişkin politikalara ve yönergelere uyduğunuzdan emin olun.

Yalnızca aşağıdaki ülkelerde fiziksel ürün satan işlemleri dağıtabilirsiniz:

Avustralya
Brezilya
Kanada
Endonezya

Japonya
Meksika
Katar
Rusya

Singapur
İsviçre
Tayland
Türkiye
Birleşik Krallık
ABD

Projenizi oluşturun

İşlem görüşmelerine ilişkin bir örnek için Node.js işlemler örneğini görüntüleyin.

Proje ayarlama

İşleminizi oluştururken, işlemleri İşlemler konsolunda yapmak istediğinizi belirtmeniz gerekir.

Projenizi ve karşılamanızı ayarlamak için aşağıdakileri yapın:

Yeni proje oluşturun veya mevcut bir projeyi içe aktarın.
Dağıt > Dizin bilgileri'ne gidin.
Ek bilgiler > İşlemler bölümünde > "İşlemleriniz, fiziksel mal işlemlerini gerçekleştirmek için Transaction API'yi kullanıyor mu?" yazan kutuyu işaretleyin.

Kullanıcının hesabını bağla (isteğe bağlı)

Kullanıcıdan ödeme almak için kendi ödeme yönteminizi kullanırken, kullanıcının orada kayıtlı ödeme yöntemlerini almak, sunmak ve ödeme yapmak için Google hesabını kendi hizmetinize bağlamanızı öneririz.

Kimlik doğrulama akışı için sesli kullanıcı arayüzünü tasarlama

Kullanıcının doğrulanıp doğrulanmadığını kontrol edin ve hesap bağlama akışını başlatın

Actions Console'da Actions Builder projenizi açın.
İşleminizde hesap bağlama işlemini başlatmak için yeni bir sahne oluşturun:
1. Sahneler'i tıklayın.
2. Yeni bir sahne eklemek için ekle (+) simgesini tıklayın.
Yeni oluşturulan sahnede, Koşullar için ekle simgesini tıklayın.
Görüşmeyle ilişkilendirilen kullanıcının doğrulanmış kullanıcı olup olmadığını kontrol eden bir koşul ekleyin. Kontrol başarısız olursa İşleminiz görüşme sırasında hesap bağlama gerçekleştiremez ve hesap bağlantısı gerektirmeyen işlevlere erişim sağlamalıdır.
1. Koşul'un altındaki Enter new expression alanına aşağıdaki mantığı girin: user.verificationStatus != "VERIFIED"
2. Geçiş bölümünde, hesap bağlama gerektirmeyen bir sahneyi veya yalnızca konuk olarak kullanılabilen işlevin giriş noktası olan bir sahne seçin.

Koşullar için ekle simgesini tıklayın.
Kullanıcının ilişkili bir kimliği yoksa hesap bağlama akışını tetiklemek için bir koşul ekleyin.
1. Koşul'un altındaki Enter new expression alanına aşağıdaki mantığı girin: user.verificationStatus == "VERIFIED"
2. Geçiş'in altında Hesap Bağlama sistem sahnesini seçin.
3. Kaydet'i tıklayın.

Kaydetme işleminden sonra projenize <SceneName>_AccountLinking adlı yeni bir hesap bağlama sistemi sahnesi eklenir.

Hesap bağlama sahnesini özelleştir

Sahneler altında, hesap bağlama sistemi sahnesini seçin.
İstemi gönder'i tıklayın ve kullanıcıya İşlem'in kimliğine neden erişmesi gerektiğini açıklamak için kısa bir cümle ekleyin (örneğin, "Tercihlerinizi kaydetmek için").
Kaydet'i tıklayın.

Koşullar bölümünde, Kullanıcı hesap bağlama işlemini başarıyla tamamlarsa'yı tıklayın.
Kullanıcı, hesabını bağlamayı kabul ederse akışın nasıl devam edeceğini yapılandırın. Örneğin, gerekli olan özel iş mantığını işlemek ve kaynak sahneye geri dönmek için webhook'u çağırın.
Kaydet'i tıklayın.

Koşullar bölümünde, Kullanıcı hesap bağlama işlemini iptal eder veya kapatırsa'yı tıklayın.
Kullanıcı, hesabını bağlamayı kabul etmezse akışın nasıl ilerleyeceğini yapılandırın. Örneğin, onay mesajı gönderin ve hesap bağlama gerektirmeyen işlevler sunan sahnelere yönlendirin.
Kaydet'i tıklayın.

Koşullar bölümünde, Sistem veya ağ hatası oluşursa'yı tıklayın.
Hesap bağlama akışı sistem veya ağ hataları nedeniyle tamamlanamıyorsa akışın nasıl devam etmesi gerektiğini yapılandırın. Örneğin, onay mesajı gönderin ve hesap bağlama gerektirmeyen işlevler sunan sahnelere yönlendirin.
Kaydet'i tıklayın.

Bilgi toplama (isteğe bağlı)

İşlem koşullarını doğrulayın (isteğe bağlı)

Kullanıcı satın alma işlemi yapmak istediğini belirtmeden hemen önce, kullanıcının işlem gerçekleştirebildiğinden emin olmalıdır. Örneğin, işleminiz arandığında "Ayakkabı sipariş etmek mi yoksa hesap bakiyenizi kontrol etmek mi istersiniz?" sorusunu sorabilirsiniz. Kullanıcı "ayakkabı siparişi verin" derse devam edebildiğinden ve kullanıcının işleme devam etmesini engelleyen ayarları düzeltmesi için bir fırsat tanımalısınız. Bunun için işlem gereksinimleri kontrolünü gerçekleştiren bir sahneye geçmeniz gerekir.

İşlem Koşulları Kontrol sahnesi oluşturun

Sahneler sekmesinden TransactionRequirementsCheck adlı yeni bir Sahne ekleyin.
Alan doldurma altında yeni alan eklemek için + simgesini tıklayın.
Tür seçin'in altında alan türü olarak actions.type.TransactionRequirementsCheckResult'i seçin.
Alan adı alanında alana TransactionRequirementsCheck adını verin.
Alan değerini geri göndermeyi özelleştir onay kutusunu etkinleştirin (varsayılan olarak etkindir).
Kaydet'i tıklayın.

İşlem gereksinimlerinin kontrol edilmesi aşağıdaki sonuçlardan biriyle sonuçlanır:

Koşullar karşılanırsa oturum parametresi başarılı bir koşulla ayarlanır ve kullanıcının sırasını oluşturmaya devam edebilirsiniz.
Koşullardan biri veya daha fazlası karşılanamıyorsa oturum parametresi bir hata durumuyla ayarlanır. Bu durumda, görüşmeyi işlem deneyiminden uzaklaştırmanız veya görüşmeyi sonlandırmanız gerekir.
- Hata durumuna neden olan hatalar kullanıcı tarafından düzeltilebilirse kullanıcıdan bu sorunu cihazında çözmesi istenir. Görüşme yalnızca ses yüzeyinde gerçekleşiyorsa kullanıcının telefonuna aktarma işlemi başlatılır.

İşlem Şartlarının Kontrol Edilmesi Kontrol sonucu

Sahneler sekmesinden yeni oluşturduğunuz TransactionRequirementsCheck sahnesini seçin.
Yeni bir koşul eklemek için Koşul bölümünde + simgesini tıklayın.

Başarılı koşulu kontrol etmek için metin alanına aşağıdaki koşul söz dizimini girin:

scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"

İmleci yeni eklediğiniz koşulun üzerine getirin ve yukarı oku tıklayarak if scene.slots.status == "FINAL" tarihinden önce yerleştirin.

İstemleri gönder'i etkinleştirin ve kullanıcıya işlem yapmaya hazır olduğunu bildiren basit bir istem gönderin:

candidates:
  - first_simple:
      variants:
        - speech: >-
            You are ready to purchase physical goods.

Geçiş'in altında başka bir sahne seçerek kullanıcının sohbete devam etmesine ve bir işlem gerçekleştirmesine izin verin.
Koşulu else if scene.slots.status == "FINAL" seçin.
İstemleri gönder'i etkinleştirin ve kullanıcıya işlem yapamayacağını bildiren basit bir istem sağlayın:
```
candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.
```
Geçiş altında, İşlemi sonlandır'ı seçerek bir kullanıcı işlem yapamıyorsa görüşmeyi sonlandırın.

Teslimat adresi iste (isteğe bağlı)

İşleminiz bir kullanıcının teslimat adresini gerektiriyorsa bunu kullanıcıdan istemelisiniz. Bu, toplam fiyatı, teslimat/teslim alma konumunu belirlemek veya kullanıcının hizmet bölgenizi içinde olmasını sağlamak için faydalı olabilir. Bunu yapmak için kullanıcıdan teslimat adresini isteyen bir sahneye geçmeniz gerekir.

Teslimat Sahnesi Oluşturma

Sahneler sekmesinden DeliveryAddress adlı yeni bir sahne ekleyin.
Alan doldurma altında yeni alan eklemek için + simgesini tıklayın.
Tür seçin bölümünde, alan türü olarak actions.type.DeliveryAddressValue'yi seçin.
Alan adı alanında alana TransactionDeliveryAddress adını verin.
Alan değerini geri göndermeyi özelleştir onay kutusunu etkinleştirin (varsayılan olarak etkindir).
Kaydet'i tıklayın.

Zaman aralığını yapılandırırken Asistan'ın dize içeren bir adres elde etme isteğini ön plana çıkarmanıza olanak tanıyan bir reason sağlayabilirsiniz.Varsayılan neden dizesi, "siparişin nereye gönderileceğini bilmektir". Bu nedenle Asistan, kullanıcıya şu soruyu sorabilir: "Siparişi nereye göndereceğimi öğrenmem için teslimat adresinizi almam gerekiyor."

Ekranın bulunduğu yüzeylerde kullanıcı, işlem için kullanmak istediği adresi seçer. Daha önce adres vermemişlerse yeni bir adres girebilirler.
Yalnızca ses yüzeylerinde Asistan, kullanıcıdan işlem için varsayılan adresini paylaşma izni ister. Daha önce adres vermediyse görüşme, giriş için bir telefona aktarılır.

Teslimat Adresi sonucunu ele almak için şu adımları uygulayın:

Sahneler sekmesinden yeni oluşturduğunuz DeliveryAddress sahnesini seçin.
Yeni bir koşul eklemek için Koşul bölümünde + simgesini tıklayın.

Başarılı koşulu kontrol etmek için metin alanına aşağıdaki koşul söz dizimini girin:

scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"

İmleci yeni eklediğiniz koşulun üzerine getirin ve yukarı oku tıklayarak if scene.slots.status == "FINAL" tarihinden önce yerleştirin.

İstemleri gönder'i etkinleştirin ve kullanıcıya adresini aldığınızı bildiren basit bir istem sağlayın:

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

Geçiş bölümünde, başka bir sahne seçerek kullanıcının görüşmeye devam etmesine izin verin.
else if scene.slots.status == "FINAL" koşulunu seçin.
İstemleri gönder'i etkinleştirin ve kullanıcıya işlem yapamayacağını bildiren basit bir istem sağlayın:
```
candidates:
  - first_simple:
      variants:
        - speech: I failed to get your delivery address.
```
Geçiş'in altında Görüşmeyi sonlandır'ı seçerek bir kullanıcı işlem yapamıyorsa görüşmeyi sonlandırın.

Sırayı oluşturun

İhtiyacınız olan kullanıcı bilgilerine sahip olduğunuzda, kullanıcıyı sipariş oluşturmaya yönlendiren bir "alışveriş sepeti montajı" deneyimi oluşturursunuz. Her işlem, ürün veya hizmetine uygun şekilde sepet montaj akışında biraz farklılık gösterir.

En temel alışveriş sepeti oluşturma deneyimi, bir kullanıcının listeden eklemek üzere bir ürün seçmesine olanak tanır. Ancak, kullanıcı deneyimini basitleştirmek amacıyla görüşmeyi tasarlayabilirsiniz. Kullanıcının en son satın alma işlemini basit bir evet veya hayır sorusuyla yeniden sipariş etmesini sağlayan bir alışveriş sepeti derleme deneyimi oluşturabilirsiniz. Kullanıcıya en çok gösterilen "öne çıkan" veya "önerilen" öğelerin yer aldığı bir bant veya liste kartı da gösterebilirsiniz.

Kullanıcının seçeneklerini görsel olarak sunmak için zengin yanıtları kullanmanızı, ayrıca görüşmeyi sadece kullanıcının sesini kullanarak alışveriş sepetini oluşturabileceği şekilde tasarlamanızı öneririz. Bazı en iyi uygulamalar ve yüksek kaliteli alışveriş sepeti kurulum deneyimleriyle ilgili örnekler için İşlem Tasarımı Yönergeleri'ne bakın.

Sipariş oluşturma

Görüşmeniz sırasında, kullanıcının satın almak istediği öğeleri toplamanız ve ardından bir Order nesnesi oluşturmanız gerekir.

En azından Order şunları içermelidir:

buyerInfo - Satın alma işlemini yapan kullanıcıyla ilgili bilgiler.
transactionMerchant - Siparişi kolaylaştıran satıcıyla ilgili bilgiler.
contents - Siparişin lineItems olarak listelenen asıl içeriği.
priceAttributes - İndirimler ve vergilerin yanı sıra siparişin toplam maliyeti dahil, siparişle ilgili fiyatlandırma ayrıntıları.

Alışveriş sepetinizi oluşturmak için Order ile ilgili yanıt dokümanlarına bakın. Sıraya bağlı olarak farklı alanlar eklemeniz gerekebileceğini unutmayın.

Aşağıdaki örnek kodda, isteğe bağlı alanlar da dahil olmak üzere siparişin tamamı gösterilmektedir:

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',
  },
};

Sipariş ve sunu seçenekleri oluşturma

Kullanıcı, siparişini onaylamadan önce önerilen bir sipariş kartı sunar. Çeşitli sipariş ve sunu seçenekleri ayarlayarak bu kartın kullanıcıya sunulma şeklini özelleştirebilirsiniz.

Aşağıda, sipariş onay kartındaki kullanıcının e-posta adresi de dahil olmak üzere, teslimat adresi gerektiren bir siparişin verilmesine ilişkin sipariş ve sunum seçenekleri verilmiştir:

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

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

Ödeme parametreleri oluşturma

paymentParameters nesnenizde, siparişi için kullanıcının ödeme yöntemini açıklayan alanlar içeren bir merchantPaymentOption bulunur. Aşağıda, Visa kredi kartı kullanan ödeme parametreleri için bir örnek verilmiştir:

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'
          }
        }]
      }
    };

Sipariş verilerini oturum parametresine kaydedin

Sipariş karşılamanızdaki sipariş verilerini bir session parametresine kaydedin. Sipariş nesnesi, aynı oturum için tüm sahnelerde kullanılır.

conv.session.params.order = {
    '@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
    order: order,
    orderOptions: orderOptions,
    presentationOptions: presentationOptions,
    paymentParameters: paymentParameters
};

Sıra öner

Oluşturduğunuz bir siparişi onaylaması veya reddetmesi için kullanıcıya sunmanız gerekir. Bunun için işlem kararı alan bir sahneye geçmeniz gerekir.

İşlem Kararı sahnesi oluştur

Sahneler sekmesinden TransactionDecision adlı yeni bir sahne ekleyin.
Alan doldurma altında yeni alan eklemek için + simgesini tıklayın.
Tür seçin bölümünde, alan türü olarak actions.type.TransactionDecisionValue'i seçin.
Alan adı alanında alana TransactionDecision adını verin.
Alan değerini geri göndermeyi özelleştir onay kutusunu etkinleştirin (varsayılan olarak etkindir).
Alanı yapılandır bölümünde, açılır menüden Oturum parametresi kullan'ı seçin.
Alanı yapılandır bölümünde,siparişi metin alanına (ör. $session.params.order) depolamak için kullanılan oturum parametresinin adını girin.
Kaydet'i tıklayın.

Asistan, bir TransactionDecisionValue alanını doldurmak amacıyla, ilettiğiniz Order öğesinin doğrudan "alışveriş sepeti önizleme kartına" dönüştürüldüğü yerleşik bir deneyim başlatır. Kullanıcı "sipariş ver" diyebilir, işlemi reddedebilir, kredi kartı veya adres gibi bir ödeme seçeneğini değiştirebilir veya siparişin içeriğini değiştirebilir.

Bu noktada kullanıcı, siparişinde de değişiklik isteğinde bulunabilir. Bu durumda, alışveriş sepeti montaj deneyimini tamamladıktan sonra karşılamanızın sipariş değişikliği isteklerini işleyebildiğinden emin olmanız gerekir.

İşlem Kararı sonucunu işleme

TransactionDecisionValue alanı doldurulduğunda kullanıcının işlem kararına verdiği yanıt bir oturum parametresinde depolanır. Bu değer şunları içerir:

ORDER_ACCEPTED,
ORDER_REJECTED,
DELIVERY_ADDRESS_UPDATED,
CART_CHANGE_REQUESTED
USER_CANNOT_TRANSACT.

Bir işlem kararı sonucunu ele almak için:

Sahneler sekmesinden yeni oluşturduğunuz TransactionDecision sahnesini seçin.
Yeni bir koşul eklemek için Koşul bölümünde + simgesini tıklayın.

Başarı koşulunu kontrol etmek için metin alanına aşağıdaki koşul söz dizimini girin:

scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

İmleci yeni eklediğiniz koşulun üzerine getirin ve yukarı oku tıklayarak if scene.slots.status == "FINAL" tarihinden önce yerleştirin.

İstemleri gönder'i etkinleştirin ve kullanıcıya siparişinin tamamlandığını bildiren basit bir istem gönderin:

candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction completed! Your order
            $session.params.TransactionDecision.order.merchantOrderId is all
            set!

Görüşmeyi sonlandırmak için Geçiş'in altında Görüşmeyi sonlandır'ı seçin.
Yeni bir koşul eklemek için Koşul bölümünde + simgesini tıklayın.

Hata koşullarını kontrol etmek için metin alanına aşağıdaki koşul söz dizimini girin:

  scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"

İmleci yeni eklediğiniz koşulun üzerine getirin ve yukarı oku tıklayarak if scene.slots.status == "FINAL" tarihinden önce yerleştirin.

İstemleri gönder'i etkinleştirin ve kullanıcıya siparişin reddedildiğini bildiren basit bir istem sağlayın:

candidates:
  - first_simple:
      variants:
        - speech: Look like you don't want to order anything. Goodbye.

Görüşmeyi sonlandırmak için Geçiş'in altında Görüşmeyi sonlandır'ı seçin.
else if scene.slots.status == "FINAL" koşulunu seçin.

İstemleri gönder'i etkinleştirin ve kullanıcıya işlem yapamadığını bildiren basit bir istem sağlayın:

candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction failed with status
            $session.params.TransactionDecision.transactionDecision

Geçiş altında, İşlemi sonlandır'ı seçerek bir kullanıcı işlem yapamıyorsa görüşmeyi sonlandırın.

Siparişi kesinleştirin ve makbuz gönderin

TransactionDecisionValue alanı ORDER_ACCEPTED sonucunu döndürdüğünde siparişi "onaylamak" için gereken işlemi (ör. kendi veritabanınızda saklama ve kullanıcıdan ödeme alma) hemen gerçekleştirmeniz gerekir.

Görüşmeyi bu yanıtla sonlandırabilirsiniz ancak konuşmanın devam etmesini sağlamak için basit bir yanıt eklemeniz gerekir. İlk sağladığınız orderUpdate kullanıcı, yanıtınızın geri kalanıyla birlikte "biletli makbuz kartını" görür. Bu kart, kullanıcının Sipariş Geçmişi'nde bulduğu makbuzu yansıtır.

Sipariş onayınız sırasında sipariş nesneniz, kullanıcının sipariş için gördüğü kimlik olan userVisibleOrderId içerebilir. Bu alan için merchantOrderId öğesini tekrar kullanabilirsiniz.

OrderUpdate nesnesinin bir parçası, kullanıcının Asistan Sipariş Geçmişi'nde bulabileceği sipariş ayrıntılarının en altında, URL düğmeleri olarak görünen bir takip işlemi nesnesi içermelidir.

Her sipariş için en az bir VIEW_DETAILS işlem İşlemi göndermeniz gerekir. Bu, mobil uygulamanızda veya web sitenizde siparişin temsili için bir derin bağlantı içermelidir.
İşleminizle ilgili görüşmedeki makbuz kartına ek olarak, işlem gerçekleştirmeyle ilgili tüm yasal şartları karşılayan resmi bir makbuz da göndermeniz gerekir.

İlk sipariş güncellemesini göndermek için:

Sahneler sekmesinden TransactionDecision sahnenizi seçin.

Koşul altında, başarı sonucunu kontrol eden koşulu seçin: ORDER_ACCEPTED

  scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

Bu koşul için Webhook'unuzu çağırın ayarını etkinleştirin ve update_order gibi bir intent işleyici adı sağlayın.

Webhook kodunuzda ilk sipariş güncellemesini göndermek için bir intent işleyici ekleyin:

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
  }));
});

Sipariş güncellemelerini gönder

Siparişin kullanım ömrü boyunca kullanıcıyı siparişin durumu hakkında bilgilendirmeniz gerekir. Sipariş durumu ve ayrıntılarıyla Orders API'ye HTTP PATCH istekleri göndererek kullanıcıya sipariş güncellemelerini gönderin.

Orders API'ye eşzamansız istekler oluşturma

Orders API'ye gönderilen sipariş güncelleme istekleri, bir erişim jetonu tarafından yetkilendirilir. Orders API'ye bir sipariş güncellemesi VERMEK için Actions Console projenizle ilişkili bir JSON hizmet hesabı anahtarını indirin ve hizmet isteği anahtarını, HTTP isteğinin Authorization üst bilgisine iletilebilecek bir hamiline ait jetonla değiştirin.

Hizmet hesabı anahtarınızı almak için aşağıdaki adımları uygulayın:

Google Cloud Console'da Menü ☰ > API'ler ve hizmetler > Kimlik bilgileri > Kimlik bilgileri oluştur > Hizmet hesabı anahtarı'na gidin.
Service Account (Hizmet Hesabı) altında New Service Account'u (Yeni Hizmet Hesabı) seçin.
Hizmet hesabını service-account olarak ayarlayın.
Rol'ü Proje > Sahip olarak ayarlayın.
Anahtar türünü JSON olarak ayarlayın.
Oluştur'u seçin.
Yerel makinenize özel bir JSON hizmet hesabı anahtarı indirilir.

Sipariş güncellemeleri kodunuzda, Google API'leri istemci kitaplığını ve "https://www.googleapis.com/auth/actions.order.developer" kapsamını kullanarak hizmet anahtarınızı bir hamle jetonuyla değiştirebilirsiniz. Yükleme adımlarını ve örnekleri API istemci kitaplığı GitHub sayfasında bulabilirsiniz.

Örnek anahtar değişimi için Node.js örneğimizdeki order-update.js bölümüne de başvurabilirsiniz.

Sipariş güncellemelerini gönder

Hizmet hesabı anahtarınızı bir OAuth hamlesi jetonuyla değiştirdikten sonra, sipariş güncellemelerini Orders API'ye yetkili PATCH istekleri olarak gönderebilirsiniz.

Orders API'nin URL'si: PATCH https://actions.googleapis.com/v3/orders/${orderId}

İsteğinizde aşağıdaki başlıkları sağlayın:

Exchange hesabınızın takas ettiği OAuth hamiline ait jetonla "Authorization: Bearer token".
"Content-Type: application/json".

PATCH isteği şu biçimde bir JSON gövdesi almalıdır:

{ "orderUpdate": OrderUpdate }

OrderUpdate nesnesi aşağıdaki üst düzey alanlardan oluşur:

updateMask - Güncellemekte olduğunuz siparişin alanları. Sipariş durumunu güncellemek için değeri purchase.status, purchase.userVisibleStatusLabel olarak ayarlayın.
order - Güncellemenin içeriği. Siparişin içeriğini güncelliyorsanız değeri, güncellenen Order nesnesine ayarlayın. Siparişin durumunu (örneğin, "CONFIRMED" yerine "SHIPPED") güncelliyorsanız nesne aşağıdaki alanları içerir:
- merchantOrderId - Order nesnenizde ayarladığınız kimlik.
- lastUpdateTime - Bu güncellemenin zaman damgası.
- purchase - Aşağıdakileri içeren bir nesne:
  - status - Siparişin PurchaseStatus olarak durumu (ör. "SHIPPED" veya "DELIVERED").
  - userVisibleStatusLabel - "Siparişiniz gönderildi ve yola çıktı" gibi sipariş durumuyla ilgili ayrıntıların gösterildiği kullanıcıya yönelik bir etiket.
userNotification (isteğe bağlı) - Bu güncelleme gönderildiğinde kullanıcının cihazında görüntülenebilecek bir userNotification nesnesi. Bu nesnenin dahil edilmesi, kullanıcının cihazında bildirimin gösterileceğini garanti etmez.

Aşağıdaki örnek kodda, siparişin durumunu DELIVERED olarak güncelleyen bir örnek OrderUpdate gösterilmiştir:

// 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}`);
}

Satın alma durumunu ayarlama

Sipariş güncellemesinin status siparişin mevcut durumu açıklayıcı olmalıdır. Güncellemenizin order.purchase.status alanında, aşağıdaki değerlerden birini kullanın:

CREATED - Sipariş, kullanıcı tarafından kabul edilir ve İşleminiz açısından "oluşturulur", ancak arka ucunuzda manuel olarak işlenmesi gerekir.
CONFIRMED - Sipariş etkin durumda ve sipariş karşılama için işleniyor.
IN_PREPARATION - Sipariş, gönderim/teslimat için hazırlanıyor (örneğin, yemek pişiriliyor veya ambalajlanıyor).
READY_FOR_PICKUP - Sipariş, alıcı tarafından teslim alınabilir.
DELIVERED - Sipariş alıcıya teslim edildi
OUT_OF_STOCK - Siparişteki bir veya daha fazla ürün stokta yok.
CHANGE_REQUESTED - Kullanıcı, siparişte değişiklik isteğinde bulundu ve değişiklik işleniyor.
RETURNED - Teslimatın ardından sipariş kullanıcı tarafından iade edildi.
REJECTED - Siparişi işleme koyamadınız, ödeme alamadıysanız veya siparişi başka şekilde "etkinleştiremiyorsanız".
CANCELLED - Sipariş kullanıcı tarafından iptal edildi.

İşleminizle ilgili her durum için sipariş güncellemeleri göndermeniz gerekir. Örneğin, siparişiniz verildikten sonra günlük kaydı için manuel işlem gerektiriyorsa ek bir işlem tamamlanana kadar CREATED tutarında bir sipariş güncellemesi gönderin. Her sipariş için durum değeri gerekmez.

Projenizi test etme

Projenizi test ederken İşleminizi bir ödeme yöntemi olmadan test etmek için İşlemler konsolunda korumalı alan modunu etkinleştirebilirsiniz. Korumalı alan modunu etkinleştirmek için şu adımları uygulayın:

Actions Console'daki gezinme panelinde Test et'i tıklayın.
Ayarlar'ı tıklayın.
Geliştirme Korumalı Alanı seçeneğini etkinleştirin.

Fiziksel işlemler için de örneğinizde isInSandbox alanını true olarak ayarlayabilirsiniz. Bu işlem, Actions konsolunda korumalı alan modu ayarını etkinleştirmekle eşdeğerdir. isInSandbox kullanan bir kod snippet'i görmek için Sipariş güncellemeleri gönderme bölümüne bakın.

Sorun giderme

Test sırasında herhangi bir sorunla karşılaşırsanız işlemlerle ilgili sorun giderme adımlarımızı okumanız gerekir.