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

Эта страница переведена с помощью Cloud Translation API.

Создание транзакций цифровой подписки

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

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

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

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

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

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

Ограничения и рекомендации по проверке

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

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

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

Предварительные условия

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

Учетная запись разработчика и учетная запись продавца в 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, выполните следующие действия:

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

Добавьте следующую строку кода внутри элемента 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>

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

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

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

В консоли Google Play выберите «Продукты для продажи в приложении», затем «Подписки» . Если вы видите предупреждение, следуйте предыдущим инструкциям, чтобы создать приложение для Android, или нажмите ссылку, чтобы создать профиль продавца.
Нажмите Создать подписку .
Заполните поля для вашего цифрового продукта. Запишите идентификатор продукта, по которому вы будете ссылаться на этот продукт в своем действии.
Нажмите Сохранить .
Повторите шаги 2–4 для каждого продукта, который вы хотите продать.

Пример подписок в консоли Google Play.

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

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

Настраивать

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

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

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

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

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

В консоли «Действия» щелкните значок с тремя точками в правом верхнем углу, затем выберите «Настройки проекта».
Найдите идентификатор проекта вашего действия.
Перейдите по этой ссылке, заменив « <project_id> » идентификатором вашего проекта: https://console.developers.google.com/apis/credentials?project=project_id
В главной навигации перейдите в раздел «Учетные данные» .
На появившейся странице нажмите «Создать учетные данные» , затем «Ключ сервисной учетной записи» .
Перейдите в раздел «Учетная запись службы» и нажмите «Новая учетная запись службы» .
Присвойте учетной записи службы имя, например digitaltransactions.
Нажмите Создать .
Установите роль Project > Owner .
Нажмите Продолжить .
Нажмите Создать ключ .
Выберите тип ключа JSON .
Нажмите «Создать ключ» и загрузите ключ учетной записи службы JSON.

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

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

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

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

В консоли «Действия» выберите «Развертывание», затем «Проверка бренда» .
Если вы не подключили ни одного объекта, сначала подключите веб-сайт:
1. Нажмите кнопку веб-ресурса ( </> ).
2. Введите URL-адрес своего веб-домена и нажмите « Подключиться» .
Google отправляет электронное письмо с дальнейшими инструкциями лицу, подтвердившему этот веб-домен в консоли поиска Google . Как только получатель этого письма выполнит эти действия, веб-сайт должен появиться в разделе «Проверка бренда» .
Если у вас есть хотя бы один подключенный веб-сайт, выполните следующие действия, чтобы подключить приложение Android:
1. В консоли «Действия» выберите «Развертывание», затем «Проверка бренда» .
2. Нажмите «Подключить приложение» .
3. На появившейся странице следуйте инструкциям, чтобы подтвердить свой веб-домен на консоли Play. Выберите приложение Play, содержащее ваши цифровые товары, и введите URL-адрес веб-домена точно так, как он показан на странице проверки бренда .
  Google еще раз отправляет подтверждающее электронное письмо подтвержденному владельцу домена. Как только они одобряют проверку, ваше приложение Play должно появиться в разделе «Проверка бренда» .
  Примечание. Ваш веб-домен появится в консоли 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) и находится ли он в регионе, где осуществляются цифровые транзакции. поддерживается.

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

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

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

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

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

На вкладке «Сцены» выберите только что созданную сцену DigitalPurchaseCheck .
В разделе «Условие» нажмите «+» , чтобы добавить новое условие.
В текстовом поле введите следующий синтаксис условия, чтобы проверить условие успеха:
```
scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"
```
Наведите курсор на только что добавленное условие и щелкните стрелку вверх, чтобы поместить его перед if scene.slots.status == "FINAL" .
Включите запросы на отправку и предоставьте простой запрос, сообщающий пользователю, что он готов совершить транзакцию:
```
candidates:
  - first_simple:
      variants:
        - speech: >-
            You are ready to purchase digital goods.
```
В разделе «Переход» выберите другую сцену, позволяющую пользователю продолжить разговор и приступить к совершению транзакции.
Выберите условие else if scene.slots.status == "FINAL" .
Включите запросы на отправку и предоставьте простой запрос, сообщающий пользователю, что он не может совершить транзакцию:
```
candidates:
  - first_simple:
      variants:
        - speech: Sorry you cannot perform a digital purchase.
```
В разделе «Переход» выберите «Завершить разговор» , чтобы завершить разговор.

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 (например, com.myapp.digitalgoods . 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': ['annual.subscription']
      },
    }, (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. Завершите покупку

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

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

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

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 .

На вкладке «Сцены» выберите только что созданную сцену CompletePurchase .
В разделе «Условие» нажмите «+» , чтобы добавить новое условие.
В текстовом поле введите следующий синтаксис условия, чтобы проверить условие успеха:
```
scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"
```
Наведите курсор на только что добавленное условие и щелкните стрелку вверх, чтобы поместить его перед if scene.slots.status == "FINAL" .
Включите запросы на отправку и предоставьте простой запрос, сообщающий пользователю, что он готов совершить транзакцию:
```
candidates:
  - first_simple:
      variants:
        - speech: >-
            Your purchase was successful.
```
В разделе «Переход» выберите «Завершить разговор» , чтобы завершить разговор.

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

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

Когда пользователь запрашивает ваше действие, объект 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"
    ]
  }
}

Проверьте свой проект

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

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