Transactions API در 3 مه 2023 منسوخ خواهد شد، قبل از غروب کنش‌های مکالمه در 13 ژوئن 2023. برای اطلاعات بیشتر، غروب کنش‌های مکالمه را ببینید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

تراکنش های فیزیکی را با پرداخت های مدیریت شده توسط بازرگان ایجاد کنید

این راهنما شما را در فرآیند توسعه یک پروژه Actions راهنمایی می‌کند که تراکنش‌های کالاهای فیزیکی را با استفاده از روش‌های پرداخت مدیریت شده توسط سایت شما ترکیب می‌کند.

جریان تراکنش

وقتی پروژه Actions شما تراکنش‌های فیزیکی را با استفاده از پرداخت‌های مدیریت‌شده توسط بازرگان انجام می‌دهد، از جریان زیر استفاده می‌کند:

پیوند دادن حساب کاربر - برای اینکه کاربر از روش پرداختی که در سرویس شما ذخیره کرده است استفاده کند، از Account Linking استفاده کنید تا حساب Google خود را با حساب خود در سرویس خود مرتبط کنید.
جمع آوری اطلاعات (اختیاری) - بسته به ماهیت تراکنش، ممکن است بخواهید اطلاعات زیر را در ابتدای مکالمه از کاربر جمع آوری کنید:
1. اعتبارسنجی الزامات تراکنش - در ابتدای بخش تراکنش مکالمه، تأیید کنید که کاربر شرایط لازم برای انجام تراکنش را دارد، مانند پیکربندی صحیح اطلاعات پرداخت و در دسترس بودن قبل از ساخت سبد خرید.
2. درخواست یک آدرس تحویل - اگر تراکنش نیاز به یک آدرس تحویل دارد، یک آدرس از کاربر جمع آوری کنید.
سفارش را بسازید - کاربر را از طریق یک "مجموعه سبد خرید" که در آن اقلامی را که می خواهند خریداری کنند، انتخاب کنند.
پیشنهاد سفارش - پس از تکمیل سبد خرید، سفارش را به کاربر پیشنهاد دهید تا بتواند صحت آن را تایید کند. اگر سفارش تأیید شود، پاسخی حاوی جزئیات سفارش و یک رمز پرداخت دریافت خواهید کرد.
سفارش را نهایی کنید و رسید ارسال کنید - با تایید سفارش، ردیابی موجودی یا سایر خدمات تکمیلی خود را به روز کنید و سپس رسید را برای کاربر ارسال کنید.
ارسال به‌روزرسانی‌های سفارش - در طول عمر انجام سفارش، با ارسال درخواست‌های PATCH به Orders API، به‌روزرسانی‌های سفارش را در اختیار کاربر قرار دهید.

محدودیت ها و دستورالعمل های بازبینی

به خاطر داشته باشید که خط‌مشی‌های اضافی برای اقدامات با تراکنش‌ها اعمال می‌شود. بررسی Actions با تراکنش‌ها می‌تواند تا شش هفته طول بکشد، بنابراین هنگام برنامه‌ریزی زمان‌بندی انتشار، آن زمان را در نظر بگیرید. برای تسهیل روند بازبینی، قبل از ارسال Action برای بررسی، مطمئن شوید که از خط‌مشی‌ها و دستورالعمل‌های تراکنش‌ها پیروی می‌کنید.

فقط می‌توانید Actionهایی را اجرا کنید که کالاهای فیزیکی را در کشورهای زیر می‌فروشند:

استرالیا
برزیل
کانادا
اندونزی

ژاپن
مکزیک
قطر
روسیه

سنگاپور
سوئیس
تایلند
ترکیه
انگلستان
ایالات متحده

پروژه خود را بسازید

برای مثالی از مکالمه تراکنش، نمونه تراکنش های Node.js را مشاهده کنید.

راه اندازی پروژه

هنگام ایجاد Action خود، باید مشخص کنید که می‌خواهید تراکنش‌ها را در کنسول Actions انجام دهید.

برای تنظیم پروژه و اجرای خود، موارد زیر را انجام دهید:

یک پروژه جدید ایجاد کنید یا یک پروژه موجود را وارد کنید.
به Deploy > Directory information بروید.
در قسمت اطلاعات اضافی > تراکنش‌ها > کادری را علامت بزنید که می‌گوید «آیا اقدامات شما از API تراکنش‌ها برای انجام تراکنش‌های کالاهای فیزیکی استفاده می‌کند؟».

پیوند دادن حساب کاربر (اختیاری)

هنگام استفاده از روش پرداخت خود برای دریافت هزینه از کاربر، توصیه می‌کنیم حساب Google او را با حسابی که با سرویس شما دارد پیوند دهید تا روش‌های پرداخت ذخیره شده در آنجا را بازیابی، ارائه و هزینه دریافت کنید.

رابط کاربری صوتی را برای جریان احراز هویت طراحی کنید

بررسی کنید که آیا کاربر تأیید شده است و جریان پیوند حساب را شروع کنید

پروژه Actions Builder خود را در Actions Console باز کنید.
یک صحنه جدید برای شروع پیوند دادن حساب در Action خود ایجاد کنید:
1. روی صحنه ها کلیک کنید.
2. برای افزودن یک صحنه جدید، روی نماد افزودن (+) کلیک کنید.
در صحنه جدید ایجاد شده، روی نماد افزودن برای Conditions کلیک کنید.
شرطی اضافه کنید که بررسی کند آیا کاربر مرتبط با مکالمه یک کاربر تأیید شده است یا خیر. اگر بررسی ناموفق باشد، Action شما نمی‌تواند پیوند حساب را در طول مکالمه انجام دهد و باید به ارائه دسترسی به عملکردی که نیازی به پیوند حساب ندارد بازگردد.
1. در قسمت Enter new expression در Condition ، منطق زیر را وارد کنید: user.verificationStatus != "VERIFIED"
2. در بخش انتقال ، صحنه‌ای را انتخاب کنید که نیازی به پیوند دادن حساب ندارد یا صحنه‌ای که نقطه ورود به عملکرد فقط مهمان است.

روی نماد افزودن برای شرایط کلیک کنید.
در صورتی که کاربر هویت مرتبطی نداشته باشد، شرطی را برای فعال کردن جریان پیوند حساب اضافه کنید.
1. در قسمت Enter new expression در Condition ، منطق زیر را وارد کنید: user.verificationStatus == "VERIFIED"
2. در بخش Transition ، صحنه سیستم پیوند حساب را انتخاب کنید.
3. روی ذخیره کلیک کنید.

پس از ذخیره، یک صحنه سیستم پیوند حساب جدید به نام <SceneName>_AccountLinking به پروژه شما اضافه می شود.

صحنه پیوند حساب را سفارشی کنید

در بخش صحنه‌ها ، صحنه سیستم پیوند دهنده حساب را انتخاب کنید.
روی Send prompt کلیک کنید و یک جمله کوتاه اضافه کنید تا به کاربر توضیح دهد که چرا Action باید به هویت او دسترسی داشته باشد (به عنوان مثال "برای ذخیره تنظیمات برگزیده").
روی ذخیره کلیک کنید.

در زیر شرایط ، روی اگر کاربر با موفقیت پیوند حساب را انجام دهد کلیک کنید.
اگر کاربر موافقت کرد که حساب خود را پیوند دهد، نحوه جریان را پیکربندی کنید. به عنوان مثال، برای پردازش هرگونه منطق تجاری سفارشی مورد نیاز و انتقال به صحنه اصلی، با webhook تماس بگیرید.
روی ذخیره کلیک کنید.

در زیر شرایط ، روی اگر کاربر پیوند دادن حساب را لغو یا رد کرد، کلیک کنید.
اگر کاربر با پیوند دادن حساب خود موافقت نکرد، نحوه جریان را پیکربندی کنید. به عنوان مثال، یک پیام تأیید ارسال کنید و به صحنه‌هایی هدایت کنید که عملکردی را ارائه می‌دهند که نیازی به پیوند دادن حساب ندارد.
روی ذخیره کلیک کنید.

در قسمت Conditions ، روی If system or network error رخ می دهد کلیک کنید.
اگر جریان پیوند حساب به دلیل خطاهای سیستم یا شبکه تکمیل نشد، چگونه جریان باید ادامه یابد. به عنوان مثال، یک پیام تأیید ارسال کنید و به صحنه‌هایی هدایت کنید که عملکردی را ارائه می‌دهند که نیازی به پیوند دادن حساب ندارد.
روی ذخیره کلیک کنید.

جمع آوری اطلاعات (اختیاری)

اعتبارسنجی الزامات تراکنش (اختیاری)

به محض اینکه کاربر اعلام کرد که مایل به خرید است، باید بررسی کنید که آیا می‌تواند تراکنش را انجام دهد. برای مثال، هنگام فراخوانی، Action شما ممکن است بپرسد: "آیا می‌خواهید کفش سفارش دهید یا موجودی حساب خود را بررسی کنید؟" اگر کاربر می گوید "سفارش سفارش دهید"، باید اطمینان حاصل کنید که آنها می توانند ادامه دهند و به آنها فرصت دهید تا تنظیماتی را که مانع از ادامه تراکنش می شوند، اصلاح کنند. برای انجام این کار، باید به صحنه ای بروید که بررسی الزامات تراکنش را انجام می دهد.

ایجاد صحنه بررسی الزامات معامله

از تب Scenes، یک صحنه جدید با نام TransactionRequirementsCheck اضافه کنید.
در قسمت Slot filling ، روی + کلیک کنید تا یک اسلات جدید اضافه کنید.
در قسمت Select type ، actions.type.TransactionRequirementsCheckResult را به عنوان نوع اسلات انتخاب کنید.
در فیلد نام اسلات، نام اسلات را TransactionRequirementsCheck قرار دهید.
کادر بررسی بازنویسی مقدار اسلات سفارشی را فعال کنید (به طور پیش فرض فعال است).
روی ذخیره کلیک کنید.

بررسی الزامات تراکنش منجر به یکی از نتایج زیر می شود:

در صورت برآورده شدن شرایط، پارامتر جلسه با شرط موفقیت تنظیم می شود و می توانید به ساخت سفارش کاربر ادامه دهید.
اگر یک یا چند مورد از الزامات برآورده نشود، پارامتر جلسه با یک شرط شکست تنظیم می شود. در این مورد، باید مکالمه را از تجربه تراکنش دور کنید یا مکالمه را پایان دهید.
- اگر هر گونه خطایی که منجر به وضعیت خرابی می شود توسط کاربر برطرف شود، از آنها خواسته می شود تا آن مشکلات را در دستگاه خود حل کنند. اگر مکالمه روی یک سطح فقط صوتی انجام شود، یک انتقال به تلفن کاربر آغاز می شود.

رسیدگی به الزامات تراکنش نتایج را بررسی کنید

از تب Scenes ، صحنه تازه ایجاد شده TransactionRequirementsCheck خود را انتخاب کنید.
در قسمت Condition ، روی + کلیک کنید تا یک شرط جدید اضافه کنید.
در قسمت متن، دستور شرط زیر را وارد کنید تا شرایط موفقیت را بررسی کنید:
```
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.
```
در بخش Transition صحنه دیگری را انتخاب کنید، که به کاربر اجازه می دهد مکالمه را ادامه دهد و تراکنش را انجام دهد.
شرط else if scene.slots.status == "FINAL" .
درخواست‌های ارسال را فعال کنید و یک اعلان ساده ارائه دهید که به کاربر اطلاع می‌دهد قادر به انجام تراکنش نیست:
```
candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.
```
در بخش انتقال ، پایان مکالمه را انتخاب کنید تا اگر کاربر قادر به انجام تراکنش نیست، مکالمه را پایان دهید.

درخواست آدرس تحویل (اختیاری)

اگر تراکنش شما به آدرس تحویل کاربر نیاز دارد، باید آن را از کاربر درخواست کنید. این ممکن است برای تعیین قیمت کل، محل تحویل / تحویل، یا برای اطمینان از اینکه کاربر در منطقه خدمات شما قرار دارد مفید باشد. برای انجام این کار، باید به صحنه ای منتقل شوید که از کاربر آدرس تحویل خود را می خواهد.

ایجاد صحنه آدرس تحویل

از برگه Scenes ، یک صحنه جدید با نام DeliveryAddress اضافه کنید.
در قسمت Slot filling ، روی + کلیک کنید تا یک اسلات جدید اضافه کنید.
در قسمت Select type ، actions.type.DeliveryAddressValue را به عنوان نوع اسلات انتخاب کنید.
در قسمت نام شکاف، نام TransactionDeliveryAddress را به شکاف بدهید.
کادر بررسی بازنویسی مقدار اسلات سفارشی را فعال کنید (به طور پیش فرض فعال است).
روی ذخیره کلیک کنید.

هنگام پیکربندی شکاف، می‌توانید reason ارائه کنید که به شما امکان می‌دهد درخواست دستیار برای به دست آوردن آدرس را با یک رشته مقدمه کنید. بنابراین، دستیار ممکن است از کاربر بپرسد: "برای اینکه بدانم سفارش را کجا ارسال کنیم، باید آدرس تحویل شما را دریافت کنم".

در سطوح دارای صفحه نمایش، کاربر انتخاب می کند که از کدام آدرس برای تراکنش استفاده کند. اگر قبلاً آدرسی نداده باشند، می توانند آدرس جدیدی وارد کنند.
در سطوح فقط صوتی، دستیار از کاربر اجازه می‌خواهد آدرس پیش‌فرض خود را برای تراکنش به اشتراک بگذارد. اگر قبلاً آدرسی نداده باشند، مکالمه برای ورود به تلفن تحویل داده می شود.

برای رسیدگی به نتیجه آدرس تحویل، این مراحل را دنبال کنید:

از تب Scenes ، صحنه DeliveryAddress تازه ایجاد شده خود را انتخاب کنید.
در قسمت Condition ، روی + کلیک کنید تا یک شرط جدید اضافه کنید.
در قسمت متن، دستور شرط زیر را وارد کنید تا شرایط موفقیت را بررسی کنید:
```
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.
```
در بخش انتقال ، پایان مکالمه را انتخاب کنید تا اگر کاربر قادر به انجام تراکنش نیست، مکالمه را پایان دهید.

نظم را بسازید

هنگامی که اطلاعات کاربری مورد نیاز خود را در اختیار داشتید، یک تجربه "مونتاژ سبد خرید" ایجاد خواهید کرد که کاربر را برای ایجاد سفارش راهنمایی می کند. هر Action یک جریان مونتاژ سبد خرید کمی متفاوت خواهد داشت که متناسب با محصول یا خدمات خود باشد.

ابتدایی ترین تجربه مونتاژ سبد خرید این است که کاربر مواردی را از فهرست انتخاب می کند تا به سفارش خود اضافه کند، اگرچه می توانید مکالمه را طوری طراحی کنید که تجربه کاربری را ساده کنید. می‌توانید یک تجربه مونتاژ سبد خرید بسازید که کاربر را قادر می‌سازد تا آخرین خرید خود را از طریق یک سوال بله یا خیر دوباره سفارش دهد. همچنین می‌توانید چرخ فلک یا کارت فهرستی از آیتم‌های «ویژه» یا «توصیه‌شده» را به کاربر ارائه دهید.

توصیه می کنیم از پاسخ های غنی برای ارائه گزینه های کاربر به صورت بصری استفاده کنید، اما مکالمه را به گونه ای طراحی کنید که کاربر بتواند تنها با استفاده از صدای خود سبد خرید خود را بسازد. برای برخی از بهترین شیوه‌ها و نمونه‌هایی از تجربیات مونتاژ سبد خرید با کیفیت بالا، به دستورالعمل‌های طراحی تراکنش‌ها مراجعه کنید.

یک سفارش ایجاد کنید

در طول مکالمه خود، باید مواردی را که کاربر می خواهد بخرد جمع آوری کنید و سپس یک شیء 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 با فیلدهایی است که روش پرداخت کاربر را برای سفارشش توصیف می کند. در زیر مثالی برای پارامترهای پرداخت با استفاده از کارت اعتباری ویزا آورده شده است:

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

سفارش را پیشنهاد دهید

پس از ایجاد سفارش، باید آن را به کاربر ارائه دهید تا تأیید یا رد شود. برای انجام این کار، باید به صحنه ای منتقل شوید که تصمیم تراکنش را انجام می دهد.

صحنه تصمیم معامله را ایجاد کنید

از تب Scenes ، یک صحنه جدید با نام TransactionDecision اضافه کنید.
در قسمت Slot filling ، روی + کلیک کنید تا یک اسلات جدید اضافه کنید.
در قسمت Select type ، actions.type.TransactionDecisionValue را به عنوان نوع اسلات انتخاب کنید.
در فیلد نام اسلات، نام TransactionDecision را به اسلات بدهید.
کادر بررسی بازنویسی مقدار اسلات سفارشی را فعال کنید (به طور پیش فرض فعال است).
در قسمت پیکربندی شکاف ، از منوی کشویی استفاده از پارامتر جلسه را انتخاب کنید.
در قسمت پیکربندی شکاف، نام پارامتر جلسه مورد استفاده برای ذخیره سفارش را در فیلد متنی وارد کنید (یعنی $session.params.order ).
روی ذخیره کلیک کنید.

در تلاش برای پر کردن شکاف TransactionDecisionValue ، دستیار یک تجربه داخلی را آغاز می‌کند که در آن Order که شما ارسال کرده‌اید مستقیماً روی یک «کارت پیش‌نمایش سبد خرید» ارائه می‌شود. کاربر می تواند بگوید "سفارش دهید"، تراکنش را رد کند، گزینه پرداخت مانند کارت اعتباری یا آدرس را تغییر دهد، یا درخواست تغییر محتویات سفارش را بدهد.

کاربر همچنین ممکن است در این مرحله درخواست تغییر در سفارش را داشته باشد. در این مورد، باید مطمئن شوید که انجام شما می‌تواند درخواست‌های تغییر سفارش را پس از اتمام تجربه مونتاژ سبد خرید انجام دهد.

رسیدگی به نتیجه تصمیم معامله

هنگامی که یک اسلات TransactionDecisionValue پر می شود، پاسخ کاربر به تصمیم تراکنش در یک پارامتر جلسه ذخیره می شود. این مقدار شامل موارد زیر است:

ORDER_ACCEPTED ،
ORDER_REJECTED ،
DELIVERY_ADDRESS_UPDATED ،
CART_CHANGE_REQUESTED
USER_CANNOT_TRANSACT .

برای رسیدگی به نتیجه تصمیم تراکنش:

از تب Scenes ، صحنه TransactionDecision تازه ایجاد شده خود را انتخاب کنید.
در قسمت Condition ، روی + کلیک کنید تا یک شرط جدید اضافه کنید.
در قسمت متن، دستور شرط زیر را وارد کنید تا شرایط موفقیت را بررسی کنید:
```
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!

در بخش انتقال ، پایان مکالمه را برای پایان دادن به مکالمه انتخاب کنید.
در قسمت Condition ، روی + کلیک کنید تا یک شرط جدید اضافه کنید.

در قسمت متن، دستور شرط زیر را برای بررسی شرایط خرابی وارد کنید:

  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 در پایین جزئیات سفارش ظاهر می شود که کاربر می تواند در تاریخچه سفارش دستیار خود پیدا کند.

شما باید حداقل یک VIEW_DETAILS اقدام پیگیری برای هر سفارش ارائه دهید. این باید حاوی یک پیوند عمیق به نمایش سفارش در برنامه تلفن همراه یا وب سایت شما باشد.
همچنین باید یک رسید رسمی از طریق ایمیل ارسال کنید که تمام شرایط قانونی برای انجام تراکنش را داشته باشد، علاوه بر کارت رسید در مکالمه Action شما.

برای ارسال به‌روزرسانی سفارش اولیه:

از تب Scenes ، صحنه TransactionDecision خود را انتخاب کنید.
در شرایط ، شرطی را انتخاب کنید که نتیجه موفقیت آمیز را بررسی می کند، ORDER_ACCEPTED :
```
  scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
```
برای این شرایط، Call your webhook را فعال کنید و یک نام کنترل کننده قصد، مانند update_order ارائه کنید.

در کد وب هوک خود، یک کنترل کننده قصد برای ارسال به‌روزرسانی سفارش اولیه اضافه کنید:

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 PATCH به Orders API همراه با وضعیت سفارش و جزئیات ارسال کنید.

درخواست های ناهمزمان را در Orders API تنظیم کنید

درخواست‌های به‌روزرسانی سفارش به Orders API توسط یک نشانه دسترسی مجاز است. برای وصله به‌روزرسانی سفارش در Orders API، یک کلید حساب سرویس JSON مرتبط با پروژه Actions Console خود را دانلود کنید، سپس کلید حساب سرویس را با یک توکن حامل که می‌تواند به سرصفحه Authorization درخواست HTTP منتقل شود، مبادله کنید.

برای بازیابی کلید حساب سرویس خود، مراحل زیر را انجام دهید:

در کنسول Google Cloud ، به Menu ☰ > APIs & Services > Credentials > Create credentials > Service key account بروید.
در قسمت Service Account ، New Service Account را انتخاب کنید.
حساب سرویس را روی service-account تنظیم کنید.
Role را روی Project > Owner تنظیم کنید.
نوع کلید را روی JSON تنظیم کنید.
ایجاد را انتخاب کنید.
یک کلید حساب سرویس JSON خصوصی در دستگاه محلی شما دانلود می شود.

در کد به‌روزرسانی‌های سفارش، می‌توانید با استفاده از کتابخانه سرویس گیرنده Google APIs و محدوده «https://www.googleapis.com/auth/actions.order.developer» کلید خدمات خود را با یک توکن حامل تعویض کنید. می‌توانید مراحل و نمونه‌های نصب را در صفحه GitHub کتابخانه کلاینت API بیابید.

همچنین می توانید به order-update.js در نمونه Node.js ما برای تبادل کلید مثال مراجعه کنید.

ارسال به روز رسانی سفارش

هنگامی که کلید حساب سرویس خود را با یک توکن حامل OAuth مبادله کردید، می توانید به روز رسانی های سفارش را به عنوان درخواست های PATCH مجاز به Orders API ارسال کنید.

URL API سفارشات: PATCH https://actions.googleapis.com/v3/orders/${orderId}

سرفصل های زیر را در درخواست خود وارد کنید:

"Authorization: Bearer token" با رمز حامل OAuth که کلید حساب سرویس خود را با آن مبادله کرده اید.
"Content-Type: application/json" .

درخواست PATCH باید بدنه 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 - سفارش توسط کاربر پذیرفته می شود و از دیدگاه Action شما "ایجاد" می شود، اما نیاز به پردازش دستی در پشتیبان شما دارد.
CONFIRMED - سفارش فعال است و برای انجام در حال پردازش است.
IN_PREPARATION - سفارش برای ارسال/تحویل آماده می شود، مانند غذا در حال پختن یا بسته بندی یک مورد.
READY_FOR_PICKUP - سفارش برای تحویل توسط گیرنده در دسترس است.
DELIVERED - سفارش به گیرنده تحویل داده شد
OUT_OF_STOCK - یک یا چند مورد در سفارش موجود نیست.
CHANGE_REQUESTED - کاربر درخواست تغییر در سفارش را داده است و تغییر در حال پردازش است.
RETURNED - سفارش پس از تحویل توسط کاربر برگردانده شده است.
REJECTED - اگر نتوانستید سفارش را پردازش کنید، شارژ کنید، یا در غیر این صورت "فعال" کنید.
CANCELLED - سفارش توسط کاربر لغو شد.

شما باید به‌روزرسانی‌های سفارش را برای هر وضعیتی که به تراکنش شما مرتبط است ارسال کنید. برای مثال، اگر تراکنش شما به پردازش دستی برای ثبت سفارش پس از ثبت نیاز دارد، یک به‌روزرسانی سفارش CREATED را تا زمانی که پردازش اضافی انجام شود، ارسال کنید. هر سفارشی به هر مقدار وضعیت نیاز ندارد.

پروژه خود را تست کنید

هنگام آزمایش پروژه خود، می‌توانید حالت sandbox را در کنسول Actions فعال کنید تا Action خود را بدون پرداخت هزینه از روش پرداخت آزمایش کنید. برای فعال کردن حالت جعبه ایمنی، مراحل زیر را دنبال کنید:

در کنسول Actions، روی Test در ناوبری کلیک کنید.
روی تنظیمات کلیک کنید.
گزینه Development Sandbox را فعال کنید.

برای تراکنش‌های فیزیکی، می‌توانید فیلد isInSandbox را نیز در نمونه خود روی true تنظیم کنید. این عمل معادل فعال کردن تنظیمات حالت sandbox در کنسول Actions است. برای دیدن قطعه کدی که از isInSandbox استفاده می کند، به بخش ارسال به روز رسانی سفارش مراجعه کنید.

عیب یابی

اگر در طول آزمایش با مشکلی مواجه شدید، باید مراحل عیب‌یابی تراکنش‌ها را بخوانید.