Xây dựng các giao dịch kỹ thuật số tiêu hao

Hướng dẫn này giải thích cách thêm các giao dịch kỹ thuật số vào cuộc trò chuyện Hành động để người dùng có thể mua hàng hoá kỹ thuật số tiêu dùng.

Thuật ngữ quan trọng: Hàng hoá kỹ thuật số tiêu dùng là một đơn vị lưu kho (SKU) một người dùng có thể sử dụng và mua nhiều lần, chẳng hạn như một lượng tiền trong trò chơi cho trò chơi Android. Hàng hoá kỹ thuật số này khác với hàng hoá không phải hàng tiêu dùng hàng hoá kỹ thuật số mà người dùng chỉ có thể mua một lần.

Để biết thêm thông tin về các sản phẩm tiêu dùng tính phí một lần, hãy tham khảo tài liệu về tính năng dành riêng cho sản phẩm tính phí một lần.

Luồng giao dịch

Hướng dẫn này trình bày từng bước phát triển khi các bước đó diễn ra trong hàng hoá kỹ thuật số luồng giao dịch. Khi xử lý các giao dịch hàng hoá kỹ thuật số, Hành động của bạn sử dụng quy trình sau:

  1. Thiết lập ứng dụng API mua hàng kỹ thuật số: Hành động của bạn sử dụng Purchases API để giao tiếp với khoảng không quảng cáo của bạn trên Google Play và giao dịch. Trước khi Hành động của bạn làm bất cứ việc gì khác, hành động này sẽ tạo một ứng dụng JWT có để giao tiếp với API mua hàng kỹ thuật số.
  2. Thu thập thông tin: Hành động của bạn thu thập thông tin cơ bản về người dùng và khoảng không quảng cáo của bạn trên Google Play để chuẩn bị cho giao dịch.
    1. Xác thực các yêu cầu về giao dịch: Hành động của bạn sử dụng khi bắt đầu quy trình mua để đảm bảo người dùng có thể giao dịch.
    2. Thu thập khoảng không quảng cáo có sẵn: Hành động của bạn sẽ kiểm tra Google Play kho hàng và xác định mặt hàng nào hiện có sẵn để mua.
  3. Tạo đơn đặt hàng: Hành động của bạn giới thiệu hàng hoá kỹ thuật số hiện có người dùng để họ có thể chọn một sản phẩm để mua.
  4. Hoàn tất giao dịch mua: Hành động của bạn sử dụng API mua hàng kỹ thuật số để bắt đầu giao dịch mua hàng bằng lựa chọn của người dùng từ Cửa hàng Google Play.
  5. Xử lý kết quả: Hành động của bạn nhận được mã trạng thái cho giao dịch và thông báo cho người dùng rằng giao dịch mua đã thành công (hoặc đã hoàn tất) các bước bổ sung).
  6. Làm cho giao dịch mua hàng lặp lại: Hành động của bạn sử dụng giao dịch mua kỹ thuật số API để "sử dụng" mặt hàng đã mua, cung cấp mặt hàng đó để mua bởi người dùng đó.

Các quy định hạn chế và nguyên tắc về bài đánh giá

Các chính sách bổ sung áp dụng cho Hành động có giao dịch. Quá trình này sẽ mất vài phút tuần để xem xét Hành động có bao gồm giao dịch, vì vậy, hãy tính đến thời điểm lập kế hoạch lịch phát hành. Để quá trình xem xét diễn ra dễ dàng hơn, hãy đảm bảo bạn tuân thủ với chính sách và nguyên tắc đối với giao dịch trước khi gửi Hành động đi xem xét.

Bạn chỉ có thể triển khai các hành động bán hàng hoá kỹ thuật số ở những quốc gia sau:

  • Úc
  • Brazil
  • Canada
  • Indonesia
  • Nhật Bản
  • Mexico
  • Nga
  • Singapore
  • Thái Lan
  • Thổ Nhĩ Kỳ
  • Vương Quốc Anh
  • Hoa Kỳ

Điều kiện tiên quyết

Trước khi đưa các giao dịch kỹ thuật số vào Hành động của mình, bạn cần có những điều kiện tiên quyết sau:

  • Đáp tài khoản nhà phát triển và một tài khoản người bán trên Google Play, để quản lý hàng hoá kỹ thuật số của bạn trong Google Play Console.

  • Một miền web trong Google Search Console. Miền này không cần phải liên kết với trang web được phát hành công khai, chúng tôi chỉ cần tham khảo miền web của bạn.

  • Ứng dụng Android có com.android.vending.BILLING quyền trong Google Play Console. Hàng hoá kỹ thuật số của bạn sẽ là “mua hàng trong ứng dụng” liên kết với ứng dụng này trong Google Play Console.

    Bạn cũng cần tạo một bản phát hành trong Play Console bằng ứng dụng này, nhưng nếu bạn không muốn công khai bản phát hành, bạn có thể tạo giai đoạn thử nghiệm alpha đóng bản phát hành.

    Nếu bạn chưa có ứng dụng Android, hãy làm theo Hướng dẫn liên kết ứng dụng Android.

  • Một hoặc nhiều sản phẩm được quản lý trong Google Play Console, vốn là hàng hoá kỹ thuật số mà bạn bán kèm theo Hành động của mình. Xin lưu ý rằng bạn không thể tạo sản phẩm được quản lý trong Play Console cho đến khi bạn thiết lập Điều kiện tiên quyết đối với ứng dụng Android.

    Nếu bạn chưa có sản phẩm được quản lý, hãy làm theo Hướng dẫn về Tạo Hàng hoá kỹ thuật số.

Liên kết ứng dụng Android

Nếu bạn hiện không có ứng dụng Android có quyền thanh toán trong Google Play Console, hãy làm theo các bước sau:

  1. Trong Android Studio hoặc IDE Android mà bạn chọn, hãy tạo một dự án mới. Chọn các lựa chọn trong lời nhắc thiết lập dự án để tạo một ứng dụng rất cơ bản.
  2. Đặt tên gói cho dự án, chẳng hạn như com.mycompany.myapp. Đừng để tên này theo mặc định vì bạn không thể tải các gói thêm com.example vào Play Console.
  3. Mở tệp AndroidManifest.xml của ứng dụng.
  4. Thêm dòng mã sau đây vào phần tử manifest:

    <uses-permission android:name="com.android.vending.BILLING" />

    Tệp AndroidManifest.xml sẽ có dạng như khối mã dưới đây:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="com.mycompany.myapp">
        <uses-permission android:name="com.android.vending.BILLING" />
    
        <application
            android:allowBackup="true"
            android:icon="@mipmap/ic_launcher"
            android:label="@string/app_name"
            android:roundIcon="@mipmap/ic_launcher_round"
            android:supportsRtl="true"
            android:theme="@style/AppTheme" />
    </manifest>
    
  5. Xây dựng ứng dụng dưới dạng tệp APK đã ký. Trong Android Studio, hãy làm theo các bước sau:

    1. Chuyển đến phần Build (Tạo), Generate Signed Bundle/APK (Tạo gói/APK có chữ ký).
    2. Nhấp vào Tiếp theo.
    3. Trong mục Đường dẫn cửa hàng chính, hãy nhấp vào Tạo mới.
    4. Điền vào từng trường rồi nhấp vào OK. Ghi lại Kho chính của bạn Mật khẩu khoá, đồng thời lưu trữ các thông tin này ở một nơi an toàn, vì bạn sẽ sử dụng chúng sau này.
    5. Nhấp vào Tiếp theo.
    6. Chọn bản phát hành.
    7. Chọn V1 (JAR Signature).
    8. Nhấp vào Hoàn tất.
    9. Sau vài giây, Android Studio sẽ tạo một tệp app-release.apk. Định vị tệp này để sử dụng sau này.
  6. Trong Google Play Console, hãy tạo một ứng dụng mới.

  7. Chuyển đến phần Bản phát hành ứng dụng.

  8. Trong phần Kênh kiểm thử khép kín, hãy chuyển đến phần Quản lý, rồi chọn Alpha.

  9. Nhấp vào nút Tạo bản phát hành.

  10. Trong phần Cho phép Google quản lý và bảo vệ khoá ký của bạn, hãy nhập chữ ký của bạn thông tin quan trọng.

  11. Tải tệp APK của bạn lên.

  12. Nhấp vào Lưu.

Tạo hàng hoá kỹ thuật số

Nếu bạn hiện chưa có hàng hoá kỹ thuật số nào trong Play Console, hãy làm theo các bước sau các bước:

  1. Trong Google Play Console, chuyển đến phần Sản phẩm trong ứng dụng, rồi chuyển đến phần Sản phẩm được quản lý. Nếu bạn thấy một cảnh báo, làm theo hướng dẫn trước đó để tạo một ứng dụng Android hoặc nhấp vào đường liên kết để tạo hồ sơ người bán.
  2. Nhấp vào Tạo sản phẩm được quản lý.
  3. Điền vào các trường cho sản phẩm kỹ thuật số của bạn. Ghi lại Mã sản phẩm. đây là cách bạn sẽ tham chiếu sản phẩm này từ Hành động của bạn.
  4. Nhấp vào Lưu.
  5. Lặp lại các bước từ 2 đến 4 cho từng sản phẩm mà bạn muốn bán.

Ví dụ về hàng tiêu dùng trong Google Play Console.

Chuẩn bị dự án Actions

Với hàng hoá kỹ thuật số của bạn được thiết lập trong Google Play Console, bạn phải bật giao dịch kỹ thuật số và liên kết dự án Actions của bạn với ứng dụng Play.

Thiết lập

Để bật tính năng giao dịch hàng hoá kỹ thuật số trong dự án Actions, hãy làm theo các bước sau các bước:

  1. Trong Bảng điều khiển Actions, hãy mở dự án của bạn hoặc tạo một dự án mới.
  2. Chuyển đến phần Deploy (Triển khai) rồi chọn Directory information (Thông tin thư mục).
  3. Trong phần Thông tin bổ sungGiao dịch, hãy đánh dấu vào hộp trong phần Do your Actions sử dụng Digital Purchase API để thực hiện giao dịch hàng hoá kỹ thuật số.
  4. Nhấp vào Lưu.

Tạo khoá API cho hàng hoá kỹ thuật số

Để gửi yêu cầu đến API hàng hoá kỹ thuật số, bạn cần tải dịch vụ JSON xuống khoá tài khoản liên kết với dự án Actions Console của bạn.

Để truy xuất khoá tài khoản dịch vụ, hãy làm theo các bước sau:

  1. Trong Bảng điều khiển Actions, hãy nhấp vào biểu tượng ba dấu chấm ở góc trên bên phải rồi đến phần Cài đặt dự án.
  2. Tìm Mã dự án cho Hành động của bạn.
  3. Truy cập vào đường liên kết này, thay thế cho "<project_id>" có mã dự án của bạn: https://console.developers.google.com/apis/credentials?project=project_id
  4. Trong thanh điều hướng chính, hãy chuyển đến phần Thông tin xác thực.
  5. Trên trang xuất hiện, hãy nhấp vào Tạo thông tin xác thực, sau đó nhấp vào Dịch vụ khoá tài khoản.
  6. Chuyển đến phần Tài khoản dịch vụ rồi nhấp vào Tài khoản dịch vụ mới.
  7. Đặt tên cho tài khoản dịch vụ, chẳng hạn như giao dịch kỹ thuật số.
  8. Nhấp vào Tạo.
  9. Đặt Vai trò thành Dự án > Chủ sở hữu.
  10. Nhấp vào Tiếp tục.
  11. Nhấp vào Tạo khoá.
  12. Chọn loại khoá JSON.
  13. Nhấp vào Tạo khoá rồi tải khoá tài khoản dịch vụ JSON xuống.

Lưu khoá tài khoản dịch vụ này vào một nơi an toàn. Bạn sẽ sử dụng khoá này trong phương thức thực hiện để tạo ứng dụng khách cho API mua hàng kỹ thuật số.

Kết nối với khoảng không quảng cáo của bạn trên Play

Để truy cập vào hàng hoá kỹ thuật số của bạn thông qua một dự án Actions, hãy liên kết với dự án của bạn dưới dạng tài sản đã kết nối.

Để kết nối ứng dụng và miền web trên Play Console với dự án Actions, hãy làm theo các bước sau:

  1. Trong Bảng điều khiển Actions, hãy chuyển đến phần Triển khai, rồi chuyển đến Xác minh thương hiệu.
  2. Nếu bạn chưa kết nối tài sản nào, trước tiên hãy kết nối một trang web:

    1. Nhấp vào nút thuộc tính web (&lt;/&gt;).
    2. Nhập URL cho miền web của bạn rồi nhấp vào Kết nối.

    Google sẽ gửi email kèm theo hướng dẫn bổ sung đến cá nhân đang cho miền web đó trong Google Search Console. Khi người nhận email này làm theo các bước đó, trang web sẽ xuất hiện trong phần Xác minh thương hiệu.

  3. Sau khi bạn có ít nhất một trang web được kết nối, hãy thực hiện các bước sau để kết nối ứng dụng Android của bạn:

    1. Trong Bảng điều khiển Actions, hãy chuyển đến phần Triển khai, rồi chuyển đến Xác minh thương hiệu.
    2. Nhấp vào Kết nối ứng dụng.
    3. Trên trang xuất hiện, hãy làm theo hướng dẫn để xác minh trang web của bạn trên Play Console. Chọn ứng dụng Play chứa hàng hoá kỹ thuật số và nhập URL miền web chính xác như được hiển thị trên Trang Xác minh thương hiệu.

      Một lần nữa, Google gửi email xác minh đến chủ sở hữu đã được xác minh của miền. Sau khi họ phê duyệt yêu cầu xác minh, ứng dụng Play của bạn sẽ xuất hiện trong phần Xác minh thương hiệu.

    4. Bật tính năng Truy cập giao dịch mua trên Play.

Hình ảnh cho thấy trang web và các ứng dụng được kết nối với dự án Actions.

Xây dựng quy trình mua

Với dự án Actions và kho hàng hoá kỹ thuật số đã được chuẩn bị, hãy tạo dựng quy trình mua hàng hoá trong webhook thực hiện cuộc trò chuyện.

1. Thiết lập ứng dụng API mua hàng kỹ thuật số

Trong webhook cho phương thức thực hiện cuộc trò chuyện, hãy tạo một ứng dụng JWT bằng dịch vụ của bạn khoá JSON của tài khoản và Phạm vi https://www.googleapis.com/auth/actions.purchases.digital.

Mã Node.js sau đây tạo ứng dụng JWT cho API mua hàng kỹ thuật số:

  const serviceAccount = {'my-file.json'};
  const request = require('request');
  const {google} = require('googleapis');

  const jwtClient = new google.auth.JWT(
    serviceAccount.client_email, null, serviceAccount.private_key,
    ['https://www.googleapis.com/auth/actions.purchases.digital'],
    null
  );

2. Thu thập thông tin

Trước khi người dùng có thể mua hàng, Hành động của bạn thu thập thông tin về khả năng mua hàng của người dùng và hàng hoá nào có sẵn từ khoảng không quảng cáo.

2. a. Xác thực các yêu cầu đối với giao dịch mua kỹ thuật số

Bạn nên đảm bảo rằng tài khoản của người dùng được thiết lập để hoạt động giao dịch trước khi cung cấp cho họ lựa chọn mua hàng. Bạn nên chuyển đổi sang cảnh DigitalPurchaseCheck. Cảnh này kiểm tra để đảm bảo rằng người dùng đã được xác minh. rằng họ đang thực hiện giao dịch trên nền tảng được cho phép (màn hình thông minh, loa thông minh hoặc Android) và chúng ở một địa phương nơi các công nghệ kỹ thuật số giao dịch được hỗ trợ.

Để tạo cảnh kiểm tra giao dịch mua kỹ thuật số, hãy làm theo các bước sau:

  1. Trên thẻ Scenes (Cảnh), hãy thêm một Cảnh mới có tên là DigitalPurchaseCheck.
  2. Trong phần Lấp đầy vùng, hãy nhấp vào dấu + để thêm vùng mới.
  3. Trong phần Chọn loại, hãy chọn actions.type.DigitalPurchaseCheckResult làm loại vị trí.
  4. Trong trường tên vùng, hãy đặt tên cho vùng chứa DigitalPurchaseCheck.
  5. Bật hộp kiểm Ghi lại giá trị vị trí Tuỳ chỉnh (được bật theo mặc định).
  6. Nhấp vào Lưu.

Quy trình kiểm tra giao dịch mua nội dung kỹ thuật số sẽ dẫn đến một trong những kết quả sau:

  • Nếu các yêu cầu được đáp ứng, thông số phiên được đặt thành công điều kiện cụ thể và bạn có thể tiếp tục cho phép người dùng mua hàng hoá kỹ thuật số.
  • Nếu một hoặc nhiều yêu cầu không thể đáp ứng được, thông số phiên sẽ là đặt với điều kiện lỗi. Trong trường hợp này, bạn nên chuyển hướng cuộc trò chuyện tránh xa trải nghiệm giao dịch hoặc kết thúc cuộc trò chuyện.

Để xử lý kết quả kiểm tra Giao dịch mua kỹ thuật số, hãy làm theo các bước sau:

  1. Trên thẻ Scenes (Cảnh), hãy chọn cảnh DigitalPurchaseCheck mà bạn mới tạo.
  2. Trong mục Điều kiện, hãy nhấp vào dấu + để thêm điều kiện mới.
  3. Trong trường văn bản, hãy nhập cú pháp điều kiện sau để kiểm tra điều kiện thành công:

    scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"
    
  4. Di chuột lên điều kiện bạn vừa thêm rồi nhấp vào mũi tên lên để đặt mã trước if scene.slots.status == "FINAL".

  5. Bật tính năng Gửi lời nhắc và đưa ra một lời nhắc đơn giản để người dùng biết họ đã sẵn sàng thực hiện giao dịch:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                You are ready to purchase digital goods.
    
  6. Trong phần Chuyển đổi, hãy chọn một cảnh khác, cho phép người dùng tiếp tục cuộc trò chuyện và tiếp tục thực hiện giao dịch.

  7. Chọn điều kiện else if scene.slots.status == "FINAL".

  8. Bật tính năng Gửi lời nhắc và đưa ra một lời nhắc đơn giản để người dùng biết họ không thể thực hiện giao dịch:

    candidates:
      - first_simple:
          variants:
            - speech: Sorry you cannot perform a digital purchase.
    
  9. Trong mục Chuyển đổi, hãy chọn Kết thúc cuộc trò chuyện để kết thúc cuộc trò chuyện.

2. b. Thu thập khoảng không quảng cáo có sẵn

Sử dụng API mua hàng kỹ thuật số để yêu cầu Cửa hàng Play mà bạn hiện có kho hàng, sau đó tạo mảng đó thành một mảng các đối tượng JSON cho mỗi sản phẩm. Bạn tham chiếu mảng này sau để cho người dùng biết những tuỳ chọn nào có sẵn để mua hàng.

Mỗi hàng hoá kỹ thuật số của bạn được biểu thị dưới dạng một SKU ở định dạng JSON. Chiến lược phát hành đĩa đơn đoạn mã Node.js sau đây trình bày định dạng dự kiến của mỗi SKU:

body = {
  skus: [
    skuId: {
      skuType: one of "SKU_TYPE_IN_APP" or "SKU_TYPE_SUBSCRIPTION"
      id: string,
      packageName: string
    }
    formattedPrice: string,
    title: string,
    description: string
  ]
}

Gửi yêu cầu POST đến https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet điểm cuối, trong đó {packageName} là tên gói ứng dụng của bạn trên Google Play Console (ví dụ: com.myapp.digitalgoods) rồi định dạng kết quả thành một mảng đối tượng SKU.

Để chỉ truy xuất hàng hoá kỹ thuật số cụ thể trong mảng kết quả, hãy liệt kê sản phẩm Mã nhận dạng của hàng hoá kỹ thuật số (như bên dưới từng sản phẩm trong ứng dụng trên Google Play Google Play Console) mà bạn muốn người dùng mua được ở body.ids.

Mã Node.js sau đây yêu cầu danh sách các hàng hoá có sẵn từ nền tảng kỹ thuật số mua hàng API và định dạng kết quả dưới dạng một mảng SKU:

return jwtClient.authorize((err, tokens) => {
    if (err) {
      throw new Error(`Auth error: ${err}`);
    }

    const packageName = 'com.example.projectname';

    request.post(`https://actions.googleapis.com/v3/packages/${packageName}/skus:batchGet`, {
      'auth': {
        'bearer': tokens.access_token,
      },
      'json': true,
      'body': {
        'conversationId': conv.session.id,
        'skuType': 'SKU_TYPE_IN_APP',
        // This request is filtered to only retrieve SKUs for the following product IDs
        'ids': ['consumable.1']
      },
    }, (err, httpResponse, body) => {
      if (err) {
        throw new Error(`API request error: ${err}`);
      }
      console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
      console.log(JSON.stringify(body));
    });
  });
});

3. Tạo đơn đặt hàng

Để bắt đầu giao dịch mua kỹ thuật số cho người dùng, hãy trình bày danh sách hàng hoá kỹ thuật số của bạn có thể mua được. Bạn có thể sử dụng nhiều loại phản hồi chi tiết để thể hiện kho hàng và nhắc người dùng lựa chọn.

Mã Node.js sau đây đọc một mảng khoảng không quảng cáo gồm các đối tượng SKU và tạo một list response (lập danh sách phản hồi) với một mục trong danh sách cho mỗi:

const items = [];
const entries = [];
skus.forEach((sku) => {
   const key = `${sku.skuId.skuType},${sku.skuId.id}`
   items.push({
       key: key
   });
   entries.push({
       name: key,
       synonyms: [],
       display: {
           title: sku.title,
           description: `${sku.description} | ${sku.formattedPrice}`,
       }
   });
});

conv.session.typeOverrides = [{
   name: 'type_name',
   mode: 'TYPE_REPLACE',
   synonym: {
       entries: entries
   }
}];

conv.add(new List({
   title: 'List title',
   subtitle: 'List subtitle',
   items: items,
}));

Tạo giao dịch mua hàng từ lựa chọn của người dùng

Sau khi người dùng chọn một mặt hàng, bạn có thể tạo đơn đặt hàng. Để làm được điều đó, dựa trên vùng quảng cáo được liên kết với mục đã chọn, bạn có thể gọi webhook của mình để tạo đơn đặt hàng. Lưu dữ liệu đơn đặt hàng vào một phiên từ phương thức thực hiện đơn hàng . Đối tượng thứ tự được dùng trên các cảnh trong cùng một phiên hoạt động.

conv.session.params.purchase = {
  "@type": "type.googleapis.com/google.actions.transactions.v3.CompletePurchaseValueSpec",
  "skuId": {
    "skuType": "<SKU_TYPE_IN_APP>",
    "id": "<SKU_ID>",
    "packageName": "<PACKAGE_NAME>"
  },
  "developerPayload": ""
};

Trong Actions Builder (Trình tạo thao tác), bạn có thể sử dụng trình chỉnh sửa JSON để định cấu hình vị trí với đối tượng đơn đặt hàng ở trên. Cả hai cách triển khai đều sử dụng cùng một định dạng cho CompletePurchaseValueSpec mà bạn có thể tìm thấy trong Tài liệu tham khảo về tải trọng webhook JSON.

4. Hoàn tất giao dịch mua

Sau khi người dùng chọn một mặt hàng, bạn có thể hoàn tất giao dịch mua. Sau khi điền vào vị trí liên kết với mục đã chọn, bạn nên chuyển đổi sang cảnh thực hiện một giao dịch mua hàng hoàn chỉnh.

Tạo cảnh mua hàng hoàn tất

  1. Trên thẻ Scenes (Cảnh), hãy thêm một cảnh mới có tên CompletePurchase.
  2. Trong phần Lấp đầy vùng, hãy nhấp vào dấu + để thêm vùng mới.
  3. Trong phần Chọn loại, hãy chọn actions.type.CompletePurchaseValue làm loại vị trí.
  4. Trong trường tên vùng, hãy đặt tên cho vùng chứa CompletePurchase.
  5. Bật hộp kiểm Ghi lại giá trị vị trí Tuỳ chỉnh (được bật theo mặc định).
  6. Trong mục Định cấu hình vùng, hãy chọn Use session parameter trong trình đơn thả xuống.
  7. Trong mục Định cấu hình vùng,hãy nhập tên của thông số phiên được dùng để hãy lưu trữ đơn đặt hàng vào trường văn bản (ví dụ: $session.params.purchase).
  8. Nhấp vào Lưu.

5. Xử lý kết quả

Một ô thuộc loại actions.type.CompletePurchaseValue có thể có các phần tử sau kết quả:

  • PURCHASE_STATUS_OK: Giao dịch mua đã thành công. Giao dịch là hoàn tất tại thời điểm này, vì vậy hãy thoát khỏi luồng giao dịch và quay lại cuộc trò chuyện của bạn.
  • PURCHASE_STATUS_ALREADY_OWNED: Giao dịch không thành công vì người dùng đã sở hữu mục đó. Tránh lỗi này bằng cách kiểm tra các giao dịch mua hàng và điều chỉnh các mục hiển thị để họ không thể chọn mua lại các mặt hàng họ đã sở hữu.
  • PURCHASE_STATUS_ITEM_UNAVAILABLE: Giao dịch không thành công vì mục được yêu cầu không có sẵn. Tránh lỗi này bằng cách kiểm tra SKU gần với thời điểm mua hàng hơn.
  • PURCHASE_STATUS_ITEM_CHANGE_REQUESTED: Giao dịch không thành công vì người dùng quyết định mua sản phẩm khác. Nhắc lại bằng cách tạo đơn đặt hàng để người dùng có thể đưa ra một quyết định khác ngay lập tức.
  • PURCHASE_STATUS_USER_CANCELLED: Giao dịch không thành công vì người dùng huỷ quy trình mua. Vì người dùng thoát khỏi luồng sớm, hỏi người dùng xem họ muốn thử thực hiện lại giao dịch hay thoát khỏi giao dịch hoàn toàn.
  • PURCHASE_STATUS_ERROR: Giao dịch không thành công vì lý do không xác định. Thông báo cho người dùng biết giao dịch không thành công và hỏi xem họ có muốn thử lại không.
  • PURCHASE_STATUS_UNSPECIFIED: Giao dịch không thành công vì lý do không xác định, dẫn đến trạng thái không xác định. Hãy xử lý trạng thái lỗi này bằng cách cho phép người dùng biết giao dịch không thành công và hỏi xem họ có muốn thử lại không.

Bạn nên xử lý từng kết quả này từ cảnh CompletePurchase.

  1. Trên thẻ Scenes (Cảnh), hãy chọn cảnh CompletePurchase mà bạn mới tạo.
  2. Trong mục Điều kiện, hãy nhấp vào dấu + để thêm điều kiện mới.
  3. Trong trường văn bản, hãy nhập cú pháp điều kiện sau để kiểm tra điều kiện thành công:

    scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"
    
  4. Di chuột lên điều kiện bạn vừa thêm rồi nhấp vào mũi tên lên để đặt mã trước if scene.slots.status == "FINAL".

  5. Bật tính năng Gửi lời nhắc và đưa ra một lời nhắc đơn giản để người dùng biết họ đã sẵn sàng thực hiện giao dịch:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Your purchase was successful.
    
  6. Trong mục Chuyển đổi, hãy chọn Kết thúc cuộc trò chuyện để kết thúc cuộc trò chuyện.

Lặp lại các bước trên cho từng loại kết quả giao dịch mua mà bạn muốn hỗ trợ.

6. Đảm bảo việc mua hàng có thể lặp lại

Sau khi giao dịch thành công, hãy gửi yêu cầu POST cho giao dịch mua kỹ thuật số API để sử dụng mặt hàng, cho phép người dùng mua lại mặt hàng đó. Gửi yêu cầu đối với https://actions.googleapis.com/v3/conversations/{sessionId}/entitlement:consume điểm cuối có mã nhận dạng của phiên tìm thấy trong session.id.

Yêu cầu POST của bạn cũng phải bao gồm đối tượng mã thông báo giao dịch mua được liên kết với giao dịch mua hàng của người dùng, được tìm thấy trong JSON yêu cầu của người dùng trong packageEntitlements.entitlements.inAppDetails.inAppPurchaseData.purchaseToken.

Đoạn mã sau đây sẽ gửi một yêu cầu consume đến API mua hàng kỹ thuật số và báo cáo xem yêu cầu đó có thành công hay không:

request.post(`https://actions.googleapis.com/v3/conversations/${conv.session.id}/entitlement:consume`, {
  'auth': {
    'bearer': tokens.access_token,
  },
  'json': true,
  'body': {
  // This purchase token is in both the purchase event and the user's entitlements
  // in their request JSON
    "purchaseToken": entitlement.purchaseToken
  },
  }, (err, httpResponse, body) => {
    if (err) {
     throw new Error(`API request error: ${err}`);
    }
  console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
  console.log(JSON.stringify(httpResponse));
  console.log(JSON.stringify(body));
  resolve(body);
});

// Make sure the consume request was successful. In production, don't notify the user; handle failures on the back end
return consumePromise.then(body => {
  const consumed = Object.keys(body).length === 0;
  if (consumed) {
    conv.add(`You successfully consumed ${id}`);
  } else {
    conv.add(`Failed to consume: ${id}`);
  }
});

Thể hiện các giao dịch mua của người dùng

Khi người dùng truy vấn Hành động của bạn, đối tượng user của yêu cầu JSON bao gồm một các giao dịch mua của họ. Hãy kiểm tra thông tin này và thay đổi dựa trên nội dung mà người dùng đã trả tiền.

Mã mẫu sau đây cho thấy đối tượng user của một yêu cầu bao gồm packageEntitlements lần mua hàng trong ứng dụng trước đây mà họ đã thực hiện cho Gói com.digitalgoods.application:

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "example_session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
      "packageEntitlements": [
        {
          "packageName": "com.digitalgoods.application",
          "entitlements": [
            {
              "sku": "non-consumable.1",
              "skuType": "SKU_TYPE_IN_APP"
            }
            {
              "sku": "consumable.2",
              "skuType": "SKU_TYPE_IN_APP"
            }
          ]
        },
        {
          "packageName": "com.digitalgoods.application",
          "entitlements": [
            {
              "sku": "annual.subscription",
              "skuType": "SKU_TYPE_SUBSCRIPTION",
              "inAppDetails": {
                "inAppPurchaseData": {
                  "autoRenewing": true,
                  "purchaseState": 0,
                  "productId": "annual.subscription",
                  "purchaseToken": "12345",
                  "developerPayload": "HSUSER_IW82",
                  "packageName": "com.digitalgoods.application",
                  "orderId": "GPA.233.2.32.3300783",
                  "purchaseTime": 1517385876421
                },
                "inAppDataSignature": "V+Q=="
              }
            }
          ]
        }
      ]
     }
   },
  "homeStructure": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Kiểm thử dự án

Khi kiểm thử dự án, bạn có thể bật chế độ hộp cát trong Bảng điều khiển Actions để thử nghiệm Hành động của bạn mà không tính phí vào một phương thức thanh toán. Để bật chế độ hộp cát, hãy làm theo các bước sau:

  1. Trong bảng điều khiển Actions, hãy nhấp vào Test (Kiểm thử) trên bảng điều hướng.
  2. Nhấp vào Cài đặt.
  3. Bật tuỳ chọn Hộp cát phát triển.