سيتم إيقاف واجهة برمجة تطبيقات المعاملات في 3 أيار (مايو) 2023، قبل إيقاف ميزة "إجراءات المحادثات" في 13 حزيران (يونيو) 2023. لمزيد من المعلومات، يُرجى الاطّلاع على إنهاء إجراءات المحادثة.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إجراء معاملات فعلية من خلال الدفعات التي يديرها التاجر

يرشدك هذا الدليل خلال عملية تطوير مشروع المهام تتضمن معاملات للسلع المادية باستخدام طرق دفع مُدارة حسب موقعك الإلكتروني

تدفق المعاملة

عندما يعالج مشروع "المهام" المعاملات المادية من خلال دفعات يديرها التاجر، التدفق التالي:

ربط حساب المستخدم: ليتمكّن المستخدم من استخدام عملية دفع الطريقة التي حفظها في خدمتك، استخدم ميزة "ربط الحساب" لربط حسابه على Google بحسابه على خدمتك
جمع المعلومات (اختياري) - اعتمادًا على طبيعة ، فيمكنك جمع المعلومات التالية من المستخدم في وقت مبكر من المحادثة:
1. التحقّق من صحة متطلبات المعاملات: في بداية قسم المعاملات في المحادثة، والتحقق من أن المستخدم يستوفي متطلبات إجراء المعاملة، مثل لأنّ معلومات الدفع مهيأة بشكل صحيح ومتاحة قبل بناء عربة التسوق.
2. طلب عنوان التسليم: إذا كانت المعاملة تتطلّب تسليمًا عنوانك، اجمع واحدًا من المستخدم.
إنشاء الطلب - وجِّه المستخدم نحو "تجميع عربة التسوق" حيث يختارون العناصر التي يريدون شراءها.
اقتراح الطلب - بعد اكتمال سلة التسوّق، يمكنك اقتراح الطلب من أجل المستخدم حتى يتمكنوا من تأكيد صحته. إذا تم تأكيد الطلب، فيجب تتلقّى ردًا يتضمّن تفاصيل الطلب ورمزًا للدفع.
إنهاء الطلب وإرسال إيصال: بعد تأكيد الطلب، يمكنك تعديل تتبُّع المستودع أو خدمات توصيل الطلبات الأخرى، ثم إرسال إيصال للمستخدم.
إرسال تعديلات الطلب: طوال فترة توصيل الطلب لتزويد المستخدم بتحديثات الطلب من خلال إرسال طلبات التصحيح إلى واجهة برمجة التطبيقات.

إرشادات المراجعة والقيود

يُرجى العلم أنّ سياسات إضافية تنطبق على "المهام مع مساعد Google". أُنشأها جون هنتر، الذي كان متخصصًا قد تستغرق مراجعة الإجراءات التي تتضمن معاملات ما يصل إلى ستة أسابيع، هذا الوقت عند التخطيط لجدول الإصدار. لتسهيل عملية المراجعة، تأكَّد من الالتزام السياسات والإرشادات المتعلقة بالمعاملات قبل إرسال الإجراء للمراجعة.

يمكنك تفعيل "المهام" التي تبيع سلعًا مادية في البلدان التالية فقط:

أستراليا
البرازيل
كندا
إندونيسيا

اليابان
المكسيك
قطر
روسيا

سنغافورة
سويسرا
تايلاند
تركيا
المملكة المتحدة
الولايات المتحدة

إنشاء مشروعك

للحصول على مثال على محادثة المعاملات، يمكنك عرض معاملات Node.js. عينة.

إعداد المشروع

عند إنشاء الإجراء الخاص بك، يجب تحديد أنّك تريد إجراء المعاملات. في وحدة تحكّم الإجراءات.

لإعداد مشروعك وتنفيذك، قم بما يلي:

أنشِئ مشروعًا جديدًا أو استورِد مشروعًا حاليًا.
انتقل إلى نشر > معلومات الدليل:
ضمن معلومات إضافية > المعاملات > حدد المربع الذي يقول "تنفيذ إجراءاتك استخدام واجهة برمجة التطبيقات للمعاملات لإجراء معاملات السلع المادية؟"

ربط حساب المستخدم (اختياري)

ننصحك بربط الحساب عند استخدام طريقة الدفع الخاصة بك لتحصيل الرسوم من المستخدم. حسابه على Google بحساب لديه مع خدمتك الخاصة لاسترداده، عرض وتحصيل رسوم من طرق الدفع المخزّنة هناك.

تصميم واجهة مستخدم صوتية لتدفق المصادقة

تحقَّق مما إذا تم التحقّق من هوية المستخدم وابدأ خطوات ربط الحساب.

افتح مشروع "أداة إنشاء المهام" في وحدة تحكُّم المهام.
أنشِئ مشهدًا جديدًا لبدء ربط الحساب في الإجراء الخاص بك:
1. انقر على المَشاهد.
2. انقر على الرمز إضافة (+) لإضافة مشهد جديد.
في المشهد الذي تم إنشاؤه حديثًا، انقر على رمز الإضافة . رمز الشروط.
أضِف شرطًا يتحقّق مما إذا كان المستخدم المرتبط بالمحادثة مستخدم معتمد. إذا تعذَّر التحقّق، لن يتمكّن الإجراء من ربط الحساب. أثناء المحادثة، وينبغي أن يعود لتوفير الوصول إلى بوظيفة لا تتطلب ربط الحسابات.
1. في الحقل Enter new expression ضمن الشرط، أدخِل المنطق التالي: user.verificationStatus != "VERIFIED"
2. ضمن نقل، اختَر مشهدًا لا يتطلّب ربط الحساب أو المشهد الذي يمثل نقطة دخول إلى وظيفة الضيوف فقط.

انقر على رمز إضافة من أجل الشروط.
إضافة شرط لبدء عملية ربط الحساب إذا لم يكن لدى المستخدم بهوية مرتبطة.
1. في الحقل Enter new expression ضمن الشرط، أدخِل المنطق التالي: user.verificationStatus == "VERIFIED"
2. ضمن الانتقال، اختَر مشهد النظام ربط الحساب.
3. انقر على حفظ.

بعد الحفظ، تم إنشاء مشهد جديد لنظام ربط الحسابات يُسمى <SceneName>_AccountLinking. تمت إضافته إلى مشروعك.

تخصيص مشهد ربط الحسابات

ضمن المَشاهد، اختَر مشهد نظام ربط الحسابات.
انقر على إرسال طلب وأضِف جملة قصيرة تصفها للمستخدم. سبب احتياج الإجراء إلى الوصول إلى هويته (مثلاً، "حفظ إعداداتك المفضّلة").
انقر على حفظ.

ضمن الشروط، انقر على إذا أكمل المستخدم ربط الحساب بنجاح.
يمكنك ضبط كيفية متابعة التدفق إذا وافق المستخدم على ربط حسابه. مثلاً، يمكنك طلب الردّ التلقائي على الويب لمعالجة أي منطق مخصّص للنشاط التجاري. والعودة إلى المشهد الأصلي.
انقر على حفظ.

ضمن الشروط، انقر على إذا ألغى المستخدم ربط الحساب أو رفضه.
قم بتهيئة كيفية متابعة التدفق إذا لم يوافق المستخدم على ربط الحساب. على سبيل المثال، يمكنك إرسال رسالة إقرار وإعادة التوجيه إلى المشاهد. التي توفّر وظائف لا تتطلّب ربط الحسابات.
انقر على حفظ.

ضمن الشروط، انقر على في حال حدوث خطأ في النظام أو الشبكة.
اضبط كيفية سير العملية إذا تعذّر إكمال عملية ربط الحساب اكتمل بسبب أخطاء في النظام أو الشبكة. على سبيل المثال، يمكنك إرسال رسالة إقرار وإعادة التوجيه إلى المشاهد. التي توفّر وظائف لا تتطلّب ربط الحسابات.
انقر على حفظ.

جمع المعلومات (اختياري)

التحقّق من صحة متطلبات المعاملة (اختياري)

عندما يبدي المستخدم رغبته في إجراء عملية شراء، يجب عليك التحقق للتأكد من أنه سيكون قادرًا على إجراء معاملة. على سبيل المثال، عند استدعاء الإجراء، قد يسأل الإجراء: "هل تريد طلب أحذية، أو التحقّق من رصيد حسابك؟" إذا قال المستخدم "طلب أحذية"، يجب عليك التأكد من أنه المتابعة ومنحه فرصة لإصلاح أي إعدادات تمنعه من ذلك من مواصلة المعاملة. للقيام بذلك، يجب عليك الانتقال إلى المشهد الذي يقوم بإجراء فحص متطلبات المعاملة.

إنشاء مشهد التحقُّق من متطلبات المعاملات

من علامة تبويب "المَشاهد"، أضِف مشهدًا جديدًا باسم TransactionRequirementsCheck.
ضمن ملء الشرائح، انقر على + لإضافة خانة جديدة.
ضمن اختيار النوع، اختر actions.type.TransactionRequirementsCheckResult. كنوع الخانة
في حقل اسم الخانة، أدخِل الاسم TransactionRequirementsCheck.
فعِّل مربّع الاختيار تخصيص كتابة قيمة الخانة (مفعَّل تلقائيًا).
انقر على حفظ.

سيؤدي فحص متطلبات المعاملة إلى إحدى النتائج التالية:

في حال استيفاء المتطلبات، يتم ضبط مَعلمة الجلسة بنجاح. الشرط ويمكنك متابعة إنشاء طلب المستخدم.
إذا تعذّر استيفاء شرط واحد أو أكثر من المتطلبات، يتم ضبط مَعلمة الجلسة. مع حالة إخفاق. في هذه الحالة، يجب عليك إبعاد المحادثة من تجربة المعاملات أو إنهاء المحادثة.
- إذا كان بإمكان المستخدم إصلاح أي أخطاء تنتج عن حالة الفشل، سيُطلب منهم حلّ هذه المشاكل على أجهزتهم. إذا كانت المحادثة على سطح من خلال الصوت فقط، وستتم عملية تسليم إلى هاتف المستخدم.

نتيجة التحقّق من متطلبات التعامل مع المعاملات

من علامة تبويب المَشاهد، اختَر المحتوى الذي أنشأته مؤخرًا مشهد واحد (TransactionRequirementsCheck)
ضمن الشرط، انقر على + لإضافة شرط جديد.
في الحقل النصي، أدخل بنية الشرط التالية للتحقق من شرط النجاح:
```
scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
```
مرِّر مؤشر الماوس فوق الشرط الذي أضفته للتو وانقر على السهم لأعلى. لوضعه قبل if scene.slots.status == "FINAL".
تفعيل إرسال الطلبات وتقديم طلب بسيط لإعلام المستخدم أنه على استعداد لإجراء معاملة:
```
candidates:
  - first_simple:
      variants:
        - speech: >-
            You are ready to purchase physical goods.
```
ضمن الانتقال، اختَر مشهدًا آخر للسماح للمستخدم بمواصلة المحادثة والمضي قدمًا في إجراء المعاملة.
اختَر الشرط else if scene.slots.status == "FINAL".
تفعيل إرسال الطلبات وتقديم طلب بسيط لإعلام المستخدم إذا لم يتمكن من إجراء معاملة:
```
candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.
```
ضمن النقل، اختَر إنهاء المحادثة لإنهاء المحادثة في حال عدم قدرة المستخدم على إجراء معاملات.

طلب عنوان التسليم (اختياري)

إذا كانت معاملتك تتطلب عنوان تسليم خاص بالمستخدم، عليك طلبه. من المستخدم. قد يكون هذا مفيدًا في تحديد السعر الإجمالي، موقع التسليم/الاستلام أو للتأكد من أن المستخدم يقع ضمن منطقة نطاق خدمتك. للقيام بذلك، يجب أن تنتقل إلى مشهد يحث المستخدم على وعنوان التسليم.

إنشاء مشهد عنوان التسليم

من علامة التبويب المَشاهد، أضِف مشهدًا جديدًا باسم DeliveryAddress.
ضمن ملء الشرائح، انقر على + لإضافة خانة جديدة.
ضمن اختيار النوع، اختَر actions.type.DeliveryAddressValue كنوع الخانة.
في حقل اسم الخانة، أدخِل الاسم TransactionDeliveryAddress.
فعِّل مربّع الاختيار تخصيص كتابة قيمة الخانة (مفعَّل تلقائيًا).
انقر على حفظ (Save).

عند ضبط الخانة، يمكنك توفير reason يتيح لك قدِّم طلب المساعد للحصول على عنوان بسلسلة. سلسلة السبب هي "معرفة مكان إرسال الطلب". لذلك، لا يمكن لمساعد Google المستخدم: "لمعرفة مكان إرسال الطلب، سأحتاج إلى الحصول على عنوان التسليم".

على مساحات العرض التي تحتوي على شاشة، سيختار المستخدم العنوان الذي يريد استخدامه. مقابل المعاملة. وإذا لم يسبق له تقديم عنوان، فسيتم تتمكن من إدخال عنوان جديد.
على مساحات العرض الصوتية فقط، سيطلب "مساعد Google" من المستخدم الإذن لتنفيذ ما يلي: مشاركة عنوانه الافتراضي لإجراء المعاملة. إذا لم يسبق عند تقديم عنوان، يتم تسليم المحادثة إلى هاتف لتسجيل الدخول.

لمعالجة نتيجة عنوان التسليم، اتبع الخطوات التالية:

من علامة التبويب المَشاهد، اختَر المشهد DeliveryAddress الذي تم إنشاؤه حديثًا.
ضمن الشرط، انقر على + لإضافة شرط جديد.
في الحقل النصي، أدخل بنية الشرط التالية للتحقق من شرط النجاح:
```
scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"
```
مرِّر مؤشر الماوس فوق الشرط الذي أضفته للتو وانقر على السهم لأعلى. لوضعه قبل if scene.slots.status == "FINAL".

تفعيل إرسال الطلبات وتقديم طلب بسيط يتيح للمستخدم أنك تلقيت عنوانه:

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

ضمن الانتقال، اختَر مشهدًا آخر للسماح للمستخدم بالمتابعة. المحادثة.
اختَر الشرط "else if scene.slots.status == "FINAL"".
تفعيل إرسال الطلبات وتقديم طلب بسيط لإعلام المستخدم إذا لم يتمكن من إجراء معاملة:
```
candidates:
  - first_simple:
      variants:
        - speech: I failed to get your delivery address.
```
ضمن النقل، اختَر إنهاء المحادثة لإنهاء المحادثة. إذا لم يتمكن المستخدم من إجراء المعاملات.

إنشاء الطلب

بمجرد حصولك على معلومات المستخدم التي تحتاجها، ستنشئ "عربة التسوق" لتجميع" الخبرة التي توجه المستخدم لإنشاء طلب. سيؤدي كل إجراء إلى يكون لها تدفق تجميع عربة مختلف قليلاً حسبما يتناسب منتجك أو خدمتك.

تتضمن التجربة الأساسية لتجميع سلة التسوق إمكانية اختيار المستخدم لعناصر من قائمة لإضافتها بترتيبها، إلا أنه يمكنك تصميم المحادثة لتبسيط تجربة المستخدم. يمكنك إنشاء تجربة تجميع عربة التسوق التي تمكن إعادة طلب آخر عملية شراء عن طريق سؤال بسيط يكون الإجابة بنعم أو لا. يمكنك أيضًا تقديم لوحة عرض دوّارة أو بطاقة قائمة بأهم العناصر "المميزة" للمستخدم. أو "مقترَح" عناصر.

نقترح استخدام عبارات تتضمن الردود لعرض خيارات المستخدم بصريًا، ولكن أيضًا تصميم المحادثة بحيث يمكن للمستخدم بناء عربة التسوق باستخدام صوته فقط. للحصول على بعض أفضل الممارسات والأمثلة على عالية الجودة لتجميع عربة التسوق، راجع إرشادات تصميم المعاملات:

إنشاء طلب

خلال محادثتك، ستحتاج إلى جمع العناصر التي يريدها المستخدم للشراء ثم إنشاء عنصر Order.

على الأقل، يجب أن يحتوي Order على ما يلي:

buyerInfo: معلومات حول المستخدم الذي يُجري عملية الشراء
transactionMerchant - معلومات عن التاجر الذي قدّم التبرّع بالترتيب.
contents: المحتوى الفعلي للطلب المدرَج على أنّه lineItems
priceAttributes - تفاصيل سعر الطلب، بما في ذلك إجمالي المبلغ تكلفة الطلب مع الخصومات والضرائب.

يُرجى الرجوع إلى Order. مستندات الرد لإنشاء سلة التسوق الخاصة بك. لاحظ أنك قد تحتاج إلى تضمين حقول مختلفة بناءً على الترتيب.

يوضح الرمز النموذجي أدناه طلبًا كاملاً، بما في ذلك الحقول الاختيارية:

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

إنشاء خيارات الطلب والعرض التقديمي

قبل أن يؤكد المستخدم طلبه، سيتم تقديم بيان بطاقة الطلب. يمكنك تخصيص طريقة تقديم هذه البطاقة للمستخدم من خلال إعداد خيارات الترتيب والعرض المختلفة.

فيما يلي خيارات الطلب والعرض التقديمي لتقديم طلب يتطلب عنوان التسليم، بما في ذلك عنوان البريد الإلكتروني للمستخدم في بطاقة تأكيد الطلب:

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

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

إنشاء مَعلمات الدفع

يحتوي كائن paymentParameters على merchantPaymentOption مع حقول. تصف طريقة الدفع التي استخدمها المستخدم لطلبه. فيما يلي مثال لمعلمات الدفع، باستخدام بطاقة الائتمان Visa:

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

حفظ بيانات الطلب في مَعلمة الجلسة

من طريقة التنفيذ، احفظ بيانات الطلب في مَعلمة session. سيتم استخدام كائن الترتيب في المشاهد المختلفة للجلسة نفسها.

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

اقتراح الطلب

بعد إنشاء طلب، يجب تقديمه إلى المستخدم لتأكيده أو رفضه. للقيام بذلك، يجب أن تنتقل إلى مشهد ينفذ قرارًا بالمعاملة.

إنشاء مشهد اتخاذ قرار المعاملة

من علامة التبويب المَشاهد، أضِف مشهدًا جديدًا باسم TransactionDecision.
ضمن ملء الشرائح، انقر على + لإضافة خانة جديدة.
ضمن اختيار النوع، اختَر actions.type.TransactionDecisionValue باعتباره ونوع الخانة.
في حقل اسم الخانة، أدخِل الاسم TransactionDecision.
فعِّل مربّع الاختيار تخصيص كتابة قيمة الخانة (مفعَّل تلقائيًا).
ضمن ضبط الخانة، اختَر استخدام مَعلمة الجلسة من القائمة المنسدلة.
ضمن ضبط الخانة، أدخِل اسم مَعلمة الجلسة المستخدَمة. لتخزين الطلب في حقل النص (أي $session.params.order).
انقر على حفظ (Save).

يحاول "مساعد Google" ملء خانة TransactionDecisionValue. تجربة مدمجة يتم فيها عرض Order التي مررت فيها مباشرةً على "بطاقة معاينة سلة التسوق". يمكن للمستخدم قول "تقديم الطلب" أو رفض المعاملة أو تغيير أحد خيارات الدفع مثل بطاقة الائتمان أو العنوان، أو طلب تغيير محتويات الطلب.

يمكن للمستخدم أيضًا طلب إجراء تغييرات على الطلب في هذه المرحلة. في هذه الحالة، يجب أن يتأكّد من أنّ طريقة توصيل الطلب قادرة على التعامل مع طلبات تغيير الطلب بعد الانتهاء من تجربة تجميع عربة التسوق.

طريقة اتخاذ قرار المعاملة

عند ملء خانة TransactionDecisionValue، يكون إجابة المستخدم على سيتمّ تخزين قرار المعاملة في مَعلمة جلسة. تحتوي هذه القيمة على ما يلي:

ORDER_ACCEPTED،
ORDER_REJECTED،
DELIVERY_ADDRESS_UPDATED،
CART_CHANGE_REQUESTED
USER_CANNOT_TRANSACT.

لمعالجة نتيجة قرار المعاملة:

من علامة التبويب المَشاهد، اختَر المشهد TransactionDecision الذي تم إنشاؤه حديثًا.
ضمن الشرط، انقر على + لإضافة شرط جديد.
في الحقل النصي، أدخِل بنية الشرط التالية للتحقّق من شرط النجاح:
```
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
```
مرِّر مؤشر الماوس فوق الشرط الذي أضفته للتو وانقر على السهم لأعلى. لوضعه قبل if scene.slots.status == "FINAL".

تفعيل إرسال الطلبات وتقديم طلب بسيط لإعلام المستخدم اكتمال طلبه:

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

ضمن النقل، اختَر إنهاء المحادثة لإنهاء المحادثة.
ضمن الشرط، انقر على + لإضافة شرط جديد.

في الحقل النصي، أدخل بنية الشرط التالية للتحقق من حالات الفشل:

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

مرِّر مؤشر الماوس فوق الشرط الذي أضفته للتو وانقر على السهم لأعلى. لوضعه قبل if scene.slots.status == "FINAL".

تفعيل إرسال الطلبات وتقديم طلب بسيط لإعلام المستخدم تم رفض الطلب:

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

ضمن النقل، اختَر إنهاء المحادثة لإنهاء المحادثة.
اختَر الشرط "else if scene.slots.status == "FINAL"".

تفعيل إرسال الطلبات وتقديم طلب بسيط يتيح للمستخدم عدم تمكّنهم من إجراء معاملة:

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

ضمن النقل، اختَر إنهاء المحادثة لإنهاء المحادثة. إذا لم يتمكن المستخدم من إجراء المعاملات.

إكمال الطلب وإرسال إيصال

عندما تعرض الخانة TransactionDecisionValue نتيجة ORDER_ACCEPTED، يجب تنفيذ أي معالجة مطلوبة من أجل "التأكيد" على الفور الـ (مثل الاحتفاظ به في قاعدة البيانات الخاصة بك وتحصيل رسوم من المستخدم).

يمكنك إنهاء المحادثة بهذا الرد، ولكن عليك تضمين رابط الرد للحفاظ على تقدم المحادثة. عندما تقدم هذه البيانات الأولية، orderUpdate، سيرى المستخدم "بطاقة إيصال مصغّرة". مع الباقي من ردك. ستعكس هذه البطاقة الإيصال الذي يعثر عليه المستخدم في سجلّ الطلبات.

أثناء تأكيد الطلب، يمكن أن يتضمّن عنصر الطلب userVisibleOrderId وهو المعرّف الذي يراه المستخدم للطلب. يمكنك إعادة استخدام merchantOrderId لهذا الحقل.

يجب أن يحتوي جزء من كائن OrderUpdate على كائن إجراء متابعة، والتي تظهر كأزرار عنوان URL في الجزء السفلي من تفاصيل الطلب التي يمكن العثور عليها في سجلّ طلبات "مساعد Google"

عليك تقديم ما لا يقل عن VIEW_DETAILS متابعة مع كل طلب. ينبغي أن يشتمل هذا على رابط لموضع معيّن للطلب على تطبيق الهاتف المحمول أو موقع الويب.
عليك أيضًا إرسال إيصال رسمي عبر البريد الإلكتروني يستوفي جميع الشروط القانونية. متطلبات إجراء المعاملات، بالإضافة إلى بطاقة الإيصال في محادثة الإجراء الخاص بك.

لإرسال تعديل أولي للطلب:

من علامة التبويب المَشاهد، اختَر المشهد في TransactionDecision.

ضِمن الشرط، اختَر الشرط الذي يتحقّق من نتيجة النجاح، ORDER_ACCEPTED:

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

بالنسبة إلى هذا الشرط، فعِّل طلب الردّ التلقائي على الويب، وأدخِل هدفًا. اسم المعالج، مثل update_order.

في رمز الردّ التلقائي على الويب، أضِف معالج intent لإرسال طلب أوّلي. تحديث:

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

إرسال آخر أخبار الطلبات

ويجب إبقاء المستخدم على اطّلاع بحالة الطلب على مدار حياته. يمكنك إرسال تعديلات طلب المستخدم من خلال إرسال HTTP. تصحيح الطلبات إلى واجهة برمجة التطبيقات Orders API مع توضيح حالة الطلب وتفاصيله.

إعداد الطلبات غير المتزامنة في Orders API

يتم السماح بطلبات تعديل الطلبات المرسَلة إلى Orders API من خلال إذن وصول الرمز المميز. لتصحيح تعديل الطلب في واجهة برمجة التطبيقات Orders API، يجب تنزيل ملف JSON. مفتاح حساب الخدمة المرتبط بمشروع "وحدة تحكّم المهام"، ثم استبدال مفتاح حساب الخدمة لرمز الحامل المميز الذي يمكن تمريره إلى عنوان Authorization لطلب HTTP.

لاسترداد مفتاح حساب الخدمة، عليك اتّباع الخطوات التالية:

في وحدة تحكُّم Google Cloud، الانتقال إلى رمز القائمة ⋮ > واجهات برمجة التطبيقات الخدمات > بيانات الاعتماد > إنشاء بيانات الاعتماد > مفتاح حساب الخدمة.
ضمن حساب الخدمة، اختَر حساب خدمة جديد.
اضبط حساب الخدمة على service-account.
ضبط الدور على مشروع > المالك:
اضبط نوع المفتاح على JSON.
اختَر إنشاء.
سيتم تنزيل مفتاح حساب خدمة JSON خاص إلى جهازك المحلي.

في رمز تعديلات الطلب، يمكنك استبدال مفتاح الخدمة برمز حامل مميّز. باستخدام مكتبة برامج Google APIs نطاق "https://www.googleapis.com/auth/actions.order.developer". يمكنك الاطّلاع على أمثلة وخطوات التثبيت في مكتبة برامج واجهة برمجة التطبيقات صفحة GitHub.

يمكنك أيضًا الرجوع إلى order-update.js في نموذج Node.js للحصول على مثال لتبادل المفاتيح.

إرسال آخر أخبار الطلبات

بعد استبدال مفتاح حساب الخدمة برمز حامل OAuth المميز، يمكنك إرسال تحديثات الطلبات كطلبات تصحيح معتمدة إلى واجهة برمجة تطبيقات الطلبات.

عنوان URL لواجهة برمجة التطبيقات Orders API: PATCH https://actions.googleapis.com/v3/orders/${orderId}

قدِّم العناوين التالية في طلبك:

"Authorization: Bearer token" يتضمن الرمز المميز لحامل OAuth الذي استبدلت مفتاح حساب الخدمة من أجله.
"Content-Type: application/json".

يجب أن يأخذ طلب التصحيح نص JSON بالتنسيق التالي:

{ "orderUpdate": OrderUpdate }

OrderUpdate من الحقول ذات المستوى الأعلى التالية:

updateMask: حقول الطلب الذي تُعدِّله لتحديث وحالة الطلب اضبط القيمة على purchase.status, purchase.userVisibleStatusLabel.
order: محتوى التعديل إذا كنت تقوم بتحديث محتوى الطلب، اضبط القيمة على عنصر Order المعدَّل. في حالة تحديث حالة الطلب (على سبيل المثال، من من "CONFIRMED" إلى "SHIPPED")، يحتوي الكائن على الحقول التالية:
- merchantOrderId: رقم التعريف نفسه الذي ضبطته في عنصر Order
- lastUpdateTime - الطابع الزمني لهذا التعديل
- purchase - كائن يحتوي على ما يلي:
  - status - حالة الطلب باعتباره PurchaseStatus على سبيل المثال "SHIPPED" أو "DELIVERED".
  - userVisibleStatusLabel - تصنيف موجه للمستخدمين يوفر تفاصيل عن حالة الطلب، مثل "تم شحن طلبك وهو على ".
userNotification (اختياري) - أ userNotification يمكن عرضه على جهاز المستخدم عند إرسال هذا التحديث. ملاحظة أن تضمين هذا الكائن لا يضمن ظهور الإشعار على جهاز المستخدم.

يعرض الرمز النموذجي التالي مثالاً على OrderUpdate يعدِّل حالة الطلب إلى DELIVERED:

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

ضبط حالة الشراء

status تعديل الطلب يجب أن يقدّم وصفًا عن الحالة الحالية للطلب. في تحديثك order.purchase.status استخدم إحدى القيم التالية:

CREATED - يقبل المستخدم الطلب ويكون "تم إنشاؤه" من المنظور الإجراء الخاص بك ولكنه يتطلب معالجة يدوية على الخادم الخلفي.
CONFIRMED: الطلب نشط وتتم معالجته ليتم تنفيذه.
IN_PREPARATION - يتم إعداد الطلب للشحن/التوصيل، مثل الطعام المطبوخة أو عنصر يتم تغليفه.
READY_FOR_PICKUP - الطلب متاح للمستلمين استلامه.
DELIVERED: تم تسليم الطلب إلى المستلم.
OUT_OF_STOCK - هناك سلعة واحدة أو أكثر في الطلب غير متوفّرة.
CHANGE_REQUESTED - طلب المستخدم إجراء تغيير على الطلب، وأصبح التغيير قيد المعالجة.
RETURNED: تم إرجاع الطلب من قِبل المستخدم بعد التسليم.
REJECTED - إذا تعذّر عليك معالجة البيانات أو تحصيل الرسوم أو غير ذلك "تفعيل" بالترتيب.
CANCELLED - ألغى المستخدم الطلب.

يجب إرسال تحديثات الطلب لكل حالة ذات صلة بـ معاملة. على سبيل المثال، إذا كانت معاملتك تتطلب المعالجة اليدوية تسجيل الطلب بعد تقديمه، وإرسال تعديل بشأن الطلب بقيمة CREATED حتى إتمام المعالجة الإضافية. لا يتطلب كل طلب كل قيمة حالة.

اختبار مشروعك

عند اختبار مشروعك، يمكنك تفعيل وضع الحماية في وحدة تحكّم المهام لاختبار الإجراء بدون تحصيل رسوم من طريقة دفع لتمكين وضع الحماية، اتبع الخطوات التالية:

في وحدة تحكّم الإجراءات، انقر على اختبار في شريط التنقّل.
انقر على الإعدادات.
فعِّل خيار وضع حماية التطوير.

بالنسبة إلى المعاملات الفعلية، يمكنك أيضًا ضبط الحقل isInSandbox على true في عينتك. يعادل هذا الإجراء تفعيل إعداد وضع الحماية في وحدة تحكم الإجراءات. للاطّلاع على مقتطف رمز يستخدم isInSandbox، يُرجى مراجعة قسم إرسال آخر أخبار الطلب.

تحديد المشاكل وحلّها

في حال مواجهة أي مشاكل أثناء الاختبار، يُرجى الاطّلاع على خطوات تحديد المشاكل وحلّها. للمعاملات