Transactions API станет устаревшим 3 мая 2023 года, а 13 июня 2023 года прекращается действие диалоговых действий. Дополнительные сведения см. в разделе Прекращение диалоговых действий .

Создавайте непотребляемые цифровые транзакции

В этом руководстве объясняется, как добавить цифровые транзакции в диалоговое действие, чтобы пользователи могли приобретать ваши нерасходуемые цифровые товары.

Ключевые термины. Нерасходуемый цифровой товар — это складская единица (SKU), которую можно приобрести только один раз, например платный доступ к дополнительному контенту в приложении Action или Android. Этот тип продукта отличается от потребляемого цифрового товара, который можно купить, использовать и выкупить.

Дополнительные сведения о нерасходуемых одноразовых продуктах см. в документации Android по одноразовым функциям отдельных продуктов .

Поток транзакций

В этом руководстве описываются все этапы разработки по мере того, как они происходят в потоке транзакций цифровых товаров. Когда ваше действие обрабатывает транзакции для цифровых товаров, оно использует следующий процесс:

  1. Настройте клиент API цифровых покупок . Ваше действие использует API цифровых покупок для связи с вашим инвентарем Google Play и выполнения транзакций. Прежде чем ваше действие сделает что-либо еще, оно создает клиент JWT со служебным ключом для связи с API цифровых покупок.
  2. Сбор информации : ваше действие собирает основную информацию о пользователе и вашем инвентаре Google Play для подготовки к транзакции.
    1. Проверка требований к транзакциям . Ваше действие использует помощник по требованиям к цифровым транзакциям в начале процесса покупки, чтобы убедиться, что пользователь может совершить транзакцию.
    2. Соберите доступный инвентарь : ваше действие проверяет ваш инвентарь в Google Play и определяет, какие предметы в настоящее время доступны для покупки.
  3. Создайте заказ : ваше действие представляет доступные цифровые товары пользователю, чтобы он мог выбрать один для покупки.
  4. Завершить покупку : ваше действие использует API цифровых покупок, чтобы инициировать покупку с выбором пользователя в магазине Google Play.
  5. Обработать результат : ваше действие получает код состояния транзакции и уведомляет пользователя об успешной покупке (или требует дополнительных действий).

Ограничения и правила проверки

К действиям с транзакциями применяются дополнительные политики. Проверка действий, включающих транзакции, может занять несколько недель, поэтому учитывайте это время при планировании графика выпуска. Чтобы упростить процесс проверки, убедитесь, что вы соблюдаете правила и рекомендации для транзакций , прежде чем отправлять действие на проверку.

Действия, которые продают цифровые товары, могут быть развернуты только в следующих странах:

  • Австралия
  • Бразилия
  • Канада
  • Индонезия
  • Япония
  • Мексика
  • Россия
  • Сингапур
  • Таиланд
  • Турция
  • Великобритания
  • Соединенные Штаты

Предпосылки

Прежде чем вы включите цифровые транзакции в свое действие, вам необходимо выполнить следующие предварительные условия:

  • Аккаунт разработчика и аккаунт продавца в Google Play для управления цифровыми товарами в консоли Google Play .

  • Веб-домен, подтвержденный в Google Search Console . Этот домен не обязательно должен быть связан с общедоступным веб-сайтом, нам просто нужно сослаться на ваш веб-домен.

  • Приложение для Android с разрешением com.android.vending.BILLING в консоли Google Play. Ваши цифровые товары будут «покупками в приложении», связанными с этим приложением в консоли Google Play.

    Вам также необходимо создать выпуск в консоли Play с этим приложением, но если вы не хотите, чтобы выпуск был общедоступным, вы можете создать закрытый альфа-выпуск .

    Если у вас еще нет приложения для Android, следуйте инструкциям по связыванию приложения для Android .

  • Один или несколько управляемых продуктов в консоли Google Play , которые являются цифровыми товарами, которые вы продаете с помощью действия. Обратите внимание, что вы не можете создавать управляемые продукты в консоли Play, пока не настроите необходимое приложение для Android.

    Если у вас еще нет управляемых продуктов, следуйте инструкциям по созданию цифровых товаров .

Свяжите приложение для Android

Если в настоящее время у вас нет приложения Android с разрешением на выставление счетов в консоли Google Play, выполните следующие действия:

  1. В Android Studio или Android IDE по вашему выбору создайте новый проект. Выберите параметры в приглашениях настройки проекта, чтобы создать очень простое приложение.
  2. Дайте проекту имя пакета, например com.mycompany.myapp . Не оставляйте это имя по умолчанию, так как вы не сможете загружать пакеты, включающие com.example в консоль Play.
  3. Откройте файл AndroidManifest.xml вашего приложения.

  4. Добавьте следующую строку кода внутри элемента manifest :

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

    Ваш файл AndroidManifest.xml должен выглядеть следующим образом:

    <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. Создайте свое приложение как подписанный APK. В Android Studio выполните следующие действия:

    1. Перейдите к сборке , сгенерируйте подписанный пакет / APK .
    2. Нажмите «Далее» .
    3. В разделе «Путь к хранилищу ключей» нажмите «Создать новый» .
    4. Заполните каждое поле, затем нажмите OK . Запишите свой пароль хранилища ключей и пароль ключа и сохраните их в надежном месте, так как вы будете использовать их позже.
    5. Нажмите «Далее» .
    6. Выберите релиз .
    7. Выберите V1 (подпись JAR) .
    8. Нажмите Готово .
    9. Через несколько секунд Android Studio создаст файл app-release.apk . Найдите этот файл для дальнейшего использования.

  6. В консоли Google Play создайте новое приложение.

  7. Перейти к выпускам приложений .

  8. В разделе «Закрытые треки» выберите «Управление» , затем «Альфа» .

  9. Нажмите кнопку «Создать релиз» .

  10. В разделе Разрешить Google управлять вашим ключом подписи и защищать его , введите информацию о ключе подписи.

  11. Загрузите ваш APK-файл.

  12. Нажмите Сохранить .

Создайте свои цифровые товары

Если в настоящее время у вас нет цифровых товаров в консоли Play, выполните следующие действия:

  1. В консоли Google Play выберите Продукты в приложении , а затем Управляемые продукты . Если вы видите предупреждение, следуйте предыдущим инструкциям, чтобы создать приложение для Android, или нажмите на ссылку, чтобы создать профиль продавца.
  2. Щелкните Создать управляемый продукт .
  3. Заполните поля для вашего цифрового продукта. Обратите внимание на идентификатор продукта, с помощью которого вы будете ссылаться на этот продукт в своем действии.
  4. Нажмите Сохранить .
  5. Повторите шаги 2-4 для каждого продукта, который вы хотите продать.

Пример нерасходуемых товаров в консоли Google Play.

Подготовьте свой проект действий

Когда ваши цифровые товары настроены в консоли Google Play, вы должны включить цифровые транзакции и связать свой проект Actions с вашим приложением Play.

Настраивать

Чтобы включить транзакции с цифровыми товарами в проекте Actions, выполните следующие действия:

  1. В консоли Actions откройте свой проект или создайте новый.
  2. Перейдите к разделу «Развернуть» , затем «Сведения о каталоге» .
  3. В разделе «Дополнительная информация и транзакции» установите флажок « Да» в разделе «Используют ли ваши действия API цифровых покупок для выполнения транзакций с цифровыми товарами» .
  4. Нажмите Сохранить .

Создайте ключ API цифровых товаров

Чтобы отправлять запросы к API цифровых товаров, вам необходимо скачать ключ сервисной учетной записи JSON, связанный с вашим проектом консоли Actions.

Чтобы получить ключ учетной записи службы, выполните следующие действия.

  1. В консоли «Действия» щелкните значок с тремя точками в правом верхнем углу, затем выберите «Настройки проекта».
  2. Найдите идентификатор проекта вашего действия.
  3. Перейдите по этой ссылке, заменив " <project_id> " идентификатором вашего проекта: https://console.developers.google.com/apis/credentials?project=project_id .
  4. В основной навигации перейдите в Credentials .
  5. На появившейся странице нажмите «Создать учетные данные» , затем «Сервисный ключ учетной записи» .
  6. Перейдите в раздел «Учетная запись службы» и нажмите «Новая учетная запись службы» .
  7. Дайте служебной учетной записи имя, например digitaltransactions.
  8. Щелкните Создать .
  9. Установите для роли Project > Owner .
  10. Нажмите Продолжить .
  11. Щелкните Создать ключ .
  12. Выберите тип ключа JSON .
  13. Нажмите Создать ключ и загрузите ключ сервисной учетной записи JSON.

Сохраните этот ключ служебной учетной записи в надежном месте. Вы будете использовать этот ключ в своем выполнении для создания клиента для API цифровых покупок.

Подключитесь к своему игровому инвентарю

Чтобы получить доступ к своим цифровым товарам из проекта Actions, свяжите свой веб-домен и приложение с вашим проектом как связанные ресурсы .

Чтобы подключить веб-домен Play console и приложение к проекту Actions, выполните следующие действия:

  1. В консоли «Действия» выберите «Развернуть» , а затем «Проверка торговой марки» .

  2. Если вы не подключили никаких свойств, сначала подключите веб-сайт:

    1. Нажмите кнопку веб-ресурса ( </> ).
    2. Введите URL-адрес своего веб-домена и нажмите Подключить .

    Google отправляет электронное письмо с дальнейшими инструкциями лицу, которое подтвердило наличие этого веб-домена в Google Search Console . После того, как получатель этого письма выполнит эти шаги, веб-сайт должен появиться в разделе «Подтверждение бренда» .

  3. Если у вас есть хотя бы один подключенный веб-сайт, выполните следующие действия, чтобы подключить приложение для Android:

    1. В консоли «Действия» выберите «Развернуть» , а затем «Проверка торговой марки» .
    2. Щелкните Подключить приложение .

    3. На появившейся странице следуйте инструкциям, чтобы подтвердить свой веб-домен в консоли Play. Выберите приложение Play, содержащее ваши цифровые товары, и введите URL-адрес веб-домена точно так, как он показан на странице подтверждения бренда .

      Google снова отправляет письмо с подтверждением подтвержденному владельцу домена. После одобрения проверки ваше приложение Play должно появиться в разделе Подтверждение бренда .

    4. Включите покупки в Access Play .

Изображение, показывающее веб-сайт и приложения, связанные с проектом Actions.

Создайте поток покупок

Подготовив свой проект Actions и инвентарь цифровых товаров, создайте процесс покупки цифровых товаров в своем веб-перехватчике выполнения разговора.

1. Настройте клиент API цифровых покупок

В веб-перехватчике выполнения бесед создайте клиент JWT с ключом JSON вашей служебной учетной записи и областью действия https://www.googleapis.com/auth/actions.purchases.digital .

Следующий код Node.js создает клиент JWT для API цифровых покупок:

  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. Соберите информацию

Прежде чем пользователь сможет совершить покупку, ваше действие собирает информацию о способности пользователя совершать покупки и о том, какие товары доступны в вашем инвентаре.

2. а. Проверка требований к цифровым покупкам

Рекомендуется убедиться, что учетная запись пользователя настроена для выполнения транзакций, прежде чем предоставить ему возможность совершить покупку. Вам следует перейти к сцене DigitalPurchaseCheck , которая проверяет, что пользователь подтвержден, что он выполняет транзакцию на разрешенной поверхности (умный дисплей, умный динамик или Android) и что он находится в регионе, где цифровые транзакции поддерживается.

Чтобы создать сцену цифровой проверки покупки, выполните следующие действия:

  1. На вкладке «Сцены» добавьте новую сцену с именем DigitalPurchaseCheck .
  2. В разделе Заполнение слота нажмите + , чтобы добавить новый слот.
  3. В разделе Select type выберите в качестве типа слота actions.type.DigitalPurchaseCheckResult .
  4. В поле имени слота дайте слоту имя DigitalPurchaseCheck .
  5. Установите флажок Настроить обратную запись значения слота (включен по умолчанию).
  6. Нажмите Сохранить .

Проверка цифровой покупки приведет к одному из следующих результатов:

  • Если требования соблюдены, параметр сеанса устанавливается с условием успеха, и вы можете приступить к разрешению пользователю покупать цифровые товары.
  • Если одно или несколько требований не могут быть выполнены, параметр сеанса устанавливается с условием отказа. В этом случае вам следует отвести разговор от транзакционного опыта или закончить разговор.

Чтобы обработать результат проверки цифровой покупки, выполните следующие действия:

  1. На вкладке «Сцены» выберите только что созданную сцену DigitalPurchaseCheck .
  2. В разделе Условие нажмите + , чтобы добавить новое условие.

  3. В текстовом поле введите следующий синтаксис условия, чтобы проверить условие успеха:

    scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"

  4. Наведите курсор на только что добавленное условие и щелкните стрелку вверх, чтобы поместить его перед if scene.slots.status == "FINAL" .

  5. Включите запросы на отправку и предоставьте пользователю простое уведомление о том, что он готов совершить транзакцию:

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

  6. В разделе «Переход» выберите другую сцену, позволяющую пользователю продолжить разговор и совершить транзакцию.

  7. Выберите условие else if scene.slots.status == "FINAL" .

  8. Включите запросы на отправку и предоставьте пользователю простое уведомление о том, что он не может выполнить транзакцию:

    candidates:
  - first_simple:
      variants:
        - speech: Sorry you cannot perform a digital purchase.

  9. В разделе «Переход» выберите «Завершить разговор» , чтобы завершить разговор.

2. б. Соберите доступный инвентарь

Используйте API цифровых покупок, чтобы запросить доступный в настоящее время инвентарь в магазине Play, а затем встройте его в массив объектов JSON для каждого продукта. Вы ссылаетесь на этот массив позже, чтобы показать пользователю, какие опции доступны для покупки.

Каждый ваш цифровой товар представлен в виде SKU в формате JSON. Следующий код Node.js описывает ожидаемое форматирование каждого 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
  ]
}

Отправьте запрос POST на конечную точку https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet , где {packageName} – это имя пакета вашего приложения в Google Play Console (например, com.myapp.digitalgoods ) и отформатируйте результат в массив объектов SKU.

Чтобы получить в результирующем массиве только определенные цифровые товары, перечислите идентификаторы цифровых товаров (как показано под каждым продуктом в приложении в консоли Google Play), которые вы хотите сделать доступными для покупки, в body.ids .

Следующий код Node.js запрашивает список доступных товаров из API цифровых покупок и форматирует результат в виде массива 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': ['nonconsumable.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. Создайте заказ

Чтобы пользователь начал цифровую покупку, представьте список своих цифровых товаров, доступных для покупки. Вы можете использовать различные расширенные типы ответов , чтобы представить свои акции и предложить пользователю сделать выбор.

Следующий код Node.js считывает инвентарный массив объектов SKU и создает ответ списка с одним элементом списка для каждого:

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

Создать покупку из выбора пользователя

Как только пользователь выбирает элемент, вы можете создать заказ. Для этого в слоте, связанном с выбранным элементом, вы можете вызвать свой веб-хук для создания заказа. Из вашего выполнения сохраните данные заказа в параметре сеанса. Объект порядка используется в разных сценах для одного и того же сеанса.

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

Вместо этого в Actions Builder вы можете использовать редактор JSON для настройки слота с указанным выше объектом заказа. Обе реализации используют один и тот же формат для CompletePurchaseValueSpec , который вы можете найти в справочнике по полезной нагрузке веб-перехватчика JSON .

4. Завершите покупку

Как только пользователь выбирает товар, вы можете завершить покупку. Как только вы заполните слот, связанный с выбранным предметом, вы должны перейти к сцене, которая выполняет полную покупку.

Создать полную сцену покупки

  1. На вкладке Сцены добавьте новую сцену с именем CompletePurchase .
  2. В разделе Заполнение слота нажмите + , чтобы добавить новый слот.
  3. В разделе Select type выберите в качестве типа слота actions.type.CompletePurchaseValue .
  4. В поле имени слота дайте слоту имя CompletePurchase .
  5. Установите флажок Настроить обратную запись значения слота (включен по умолчанию).
  6. В разделе «Настроить слот» выберите Use session parameter в раскрывающемся списке.
  7. В разделе «Настройка слота» введите имя параметра сеанса, используемого для хранения заказа, в текстовое поле (например, $session.params.purchase ).
  8. Нажмите Сохранить .

5. Обработайте результат

Слот с типом actions.type.CompletePurchaseValue может иметь следующие результаты:

  • PURCHASE_STATUS_OK : покупка прошла успешно. На этом транзакция завершена, поэтому выйдите из потока транзакций и вернитесь к разговору.
  • PURCHASE_STATUS_ALREADY_OWNED : транзакция завершилась неудачно, поскольку пользователь уже владеет этим товаром. Избегайте этой ошибки, проверяя предыдущие покупки пользователя и адаптируя отображаемые товары таким образом, чтобы у них не было возможности повторно купить товары, которые у них уже есть.
  • PURCHASE_STATUS_ITEM_UNAVAILABLE : транзакция не выполнена, так как запрошенный товар недоступен. Избегайте этой ошибки, проверяя доступные SKU ближе к моменту покупки.
  • PURCHASE_STATUS_ITEM_CHANGE_REQUESTED : транзакция не удалась, поскольку пользователь решил купить что-то еще. Повторите запрос при построении заказа, чтобы пользователь мог сразу принять другое решение.
  • PURCHASE_STATUS_USER_CANCELLED : транзакция не удалась, так как пользователь отменил процесс покупки. Поскольку пользователь преждевременно вышел из потока, спросите пользователя, хотят ли они повторить транзакцию или вообще выйти из транзакции.
  • PURCHASE_STATUS_ERROR : транзакция не удалась по неизвестной причине. Сообщите пользователю, что транзакция не удалась, и спросите, не хотят ли они повторить попытку.
  • PURCHASE_STATUS_UNSPECIFIED : транзакция не удалась по неизвестной причине, что привело к неизвестному статусу. Обработайте этот статус ошибки, сообщив пользователю, что транзакция не удалась, и спросите, не хотят ли они повторить попытку.

Вы должны обрабатывать каждый из этих результатов из сцены CompletePurchase .

  1. На вкладке «Сцены» выберите только что созданную сцену CompletePurchase .
  2. В разделе Условие нажмите + , чтобы добавить новое условие.

  3. В текстовом поле введите следующий синтаксис условия, чтобы проверить условие успеха:

    scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"

  4. Наведите курсор на только что добавленное условие и щелкните стрелку вверх, чтобы поместить его перед if scene.slots.status == "FINAL" .

  5. Включите запросы на отправку и предоставьте пользователю простое уведомление о том, что он готов совершить транзакцию:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Your purchase was successful.

  6. В разделе «Переход» выберите «Завершить разговор» , чтобы завершить разговор.

Повторите вышеуказанные шаги для каждого типа результата покупки, который вы хотите поддерживать.

Отражение покупок пользователя

Когда пользователь запрашивает ваше действие, user объект запроса JSON включает список его покупок. Проверьте эту информацию и измените ответ вашего действия в зависимости от того, за какой контент заплатил пользователь.

В следующем примере кода показан user объект запроса, который включает в себя packageEntitlements предыдущих покупок в приложении, которые они сделали для пакета 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"
    ]
  }
}

Протестируйте свой проект

При тестировании своего проекта вы можете включить режим песочницы в консоли действий, чтобы протестировать действие без взимания платы за способ оплаты. Чтобы включить режим песочницы, выполните следующие действия:

  1. В консоли «Действия» щелкните «Тест» в области навигации.
  2. Щелкните Настройки .
  3. Включите опцию «Песочница разработки» .