Руководство по внутренней интеграции для монетизации за пределами Google Play Billing

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

Есть несколько компонентов, которые могут потребоваться для обработки покупок в приложении с вашего бэкэнда. Чтобы их создать, вам необходимо настроить интеграцию с серверной частью, как указано в разделе «Настройка API разработчика Google Play» . Ко всем внутренним функциям разработчика, которые не относятся к альтернативным API-интерфейсам выставления счетов или внешним предложениям, применяются инструкции из документации по системе выставления счетов Google Play .

Сообщайте о новых внешних транзакциях в Google Play

Интегрируйте Externaltransactions APIs , чтобы сообщать о транзакциях, происходящих за пределами платежной системы Google Play в поддерживаемых странах, включая транзакции стоимостью 0 долларов США, возникающие в результате бесплатных пробных покупок. Транзакции в альтернативных системах выставления счетов или внешних предложениях следует начинать и сообщать только для соответствующих стран-пользователей, как это разрешено в рамках программ альтернативных выставления счетов или внешних предложений , в противном случае вызов API будет отклонен. Это относится ко всем транзакциям, включая новые покупки, продления, пополнения, обновления, понижения и другие.

Отчетность о внешних транзакциях

Вам следует вызвать Externaltransactions API , чтобы сообщить о внешней транзакции после того, как платеж был авторизован через альтернативную систему выставления счетов или внешнюю систему предложений. Это относится ко всем транзакциям, включая первоначальные платежи, продления, возвраты и т. д. Обо всех транзакциях необходимо сообщать в течение 24 часов с момента совершения транзакции.

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

Сообщить о новой покупке

Каждый раз, когда новая покупка в альтернативной системе биллинга или внешних предложениях оказывается успешной, требуется вызов API Externaltransactions . Для этих новых покупок вам необходимо предоставить уникальный externalTransactionId связанный с покупкой в ​​вашей серверной части, в качестве параметра запроса. Этот externalTransactionId нельзя повторно использовать в идентификаторе пакета того же приложения.

externalTransactionToken , полученный приложением через обратные вызовы UserChoiceBillingListener , AlternativeBillingOnlyReportingDetailsListener или ExternalOfferReportingDetailsListener , также требуется как часть тела запроса для разовых покупок и первых транзакций в повторяющихся покупках (например, подписке). В любом случае это называется начальной транзакцией . После первоначальной транзакции externalTransactionToken больше не нужен, и вы сообщаете о последующих транзакциях (например, продлении подписки), предоставляя новый уникальный externalTransactionId . Дополнительные сведения о том, как сообщить о последующих транзакциях, см. в разделе «Сообщить о последующих транзакциях для покупки» .

Пример :

1. Разработчик настраивает и включает альтернативный способ оплаты в своем приложении.
2. Пользователь 1 находится в Южной Корее, поддерживаемой стране, и пытается купить product1 за 12634,10 вон в месяц с предложением бесплатной пробной версии на один месяц.
3. Приложение запускает процесс покупки с ProductDetails для product1 и предложения, выбранного пользователем.
4. Пользователь 1 выбирает альтернативную систему биллинга разработчика.
5. UserChoiceBillingListener получает значение my_token в качестве externalTransactionToken .
6. Затем разработчик отправляет соответствующую информацию на свой сервер (значение externalTransactionToken и приобретаемые продукты). Затем они запускают поток покупки product1 в альтернативной биллинговой системе. Этой транзакции присваивается уникальный идентификатор транзакции на стороне разработчика, который используется для сообщения о ней в Google Play: 123-456-789 . Идентификатор транзакции является обязательным, даже если пользователь получает бесплатную пробную версию.
7. После того как транзакция на покупку происходит в альтернативной биллинговой системе, разработчик сообщает о транзакции в Google Play следующим запросом. Первоначально об этом сообщается как о транзакции с нулевой стоимостью, поскольку пользователь получает бесплатный месяц.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Если транзакция с пользователем, проживающим в Индии, где размер налогов варьируется, зависит от его административной области (например, штата или провинции), обязательно включите эту область в userTaxAddress . Обратитесь к предопределенному списку строк в справочном руководстве API для соответствующих административных областей.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
"transactionTime" : "2023-11-01T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   # Tax varies in India based on state, so include that information in
   # administrativeArea
   "regionCode": "IN"
   "administrativeArea": "KERALA"
 }
}

Сообщайте о последующих транзакциях для покупки

В некоторых случаях с одной и той же внешней покупкой связано несколько пользовательских платежей (например, продление подписки или пополнение предоплаченного плана). Вы можете сообщить об этих последующих транзакциях, используя тот же API в Externaltransactions . Как описано в разделе «Сообщить о новой покупке» , externalTransactionToken не требуется для последующих транзакций. Вместо этого новый уникальный externalTransactionId отправляется в качестве параметра запроса для каждой транзакции продления или пополнения счета, при этом идентификатор начальной транзакции включен в поле initialExternalTransactionId .

Следуя предыдущему примеру:

1. Первое продление подписки Пользователя 1 происходит в альтернативной системе выставления счетов. Первоначальный идентификатор транзакции был 123-456-789 .
2. Разработчик сообщает о повторении транзакции в параметре URL-запроса как идентификатор внешней транзакции для этой новой транзакции, ссылаясь при этом на идентификатор внешней транзакции исходной транзакции в поле initialExternalTransactionId .

Пример запроса :

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "12634000000",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId": "123-456-789",

   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Сообщить об обновлении или понижении версии

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

Переход от ручного составления отчетов об альтернативных платежных транзакциях

Чтобы перенести активные подписки, которые начались, когда вы предлагали альтернативное выставление счетов без автоматической отчетности, создайте новую транзакцию с нулевой стоимостью, используя migratedTransactionProgram вместо указания initialExternalTransactionId или externalTransactionToken . Задайте для transactionTime время, когда пользователь первоначально подписался на каждую активную подписку. После этого сообщайте о каждой последующей транзакции для этих подписок как обычно через API, предоставляя initialExternalTransactionId использованный выше для создания транзакций продления. После переноса подписки вам больше не нужно будет вручную сообщать о последующих транзакциях по подписке, при условии, что они сообщаются с помощью автоматизированных методов, описанных на этой странице.

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

migratedTransactionProgram можно использовать только при переходе от отчетов вручную. Он станет устаревшим, когда отчеты вручную перестанут поддерживаться.

Пример запроса :

# Note that the externalTransactionId specified here will used to report subsequent
# transactions.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
 # Be sure to set the price to 0 for this transaction since it does not reflect
 # an actual subscription renewal.
 "originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },

 # The transaction time should be set to when the user signed up for this
 # subscription.
 "transactionTime" : "2022-02-22T12:45:00Z",
  "recurringTransaction" : {
    "migratedTransactionProgram": "USER_CHOICE_BILLING",

    "externalSubscription" {
      "subscriptionType": "RECURRING"
    }
  },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Пожаловаться на партнерские программы Play

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

Сообщите о возврате средств за покупку в Google Play

Интегрируйтесь с API Externaltransactions , чтобы сообщать о транзакциях, возвращенных пользователям за пределами платежной системы Google Play. Чтобы Play правильно определил, какая транзакция была возвращена, вам следует включить соответствующий externalTransactionId для ранее зарегистрированной транзакции как часть параметров URL.

Сообщая о возврате средств за покупки подписки, укажите externalTransactionId конкретного повторения подписки, по которой осуществляется возврат средств.

Пример : предположим, что подписка имеет следующие транзакции:

• Первоначальная транзакция с идентификатором внешней транзакции ABC.1234-5678-9012-34567.
• Первая повторяющаяся транзакция с идентификатором внешней транзакции ABC.1234-5678-9012-34567..0
• Вторая повторяющаяся транзакция с идентификатором внешней транзакции ABC.1234-5678-9012-34567..1

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

Этот метод принимает как полный возврат средств (когда сумма равна сумме, которую пользователь заплатил в исходной внешней транзакции), так и частичный возврат (когда сумма меньше суммы, которую пользователь заплатил в исходной внешней транзакции). Для частичного возврата необходимо указать сумму возврата до уплаты налогов.

API-квоты

На API Externaltransactions распространяются ежедневные квоты API для всех вызовов, как и на любую другую конечную точку в API разработчика Google Play.

Кроме того, API Externaltransactions имеет ограничение в 1200 запросов в минуту (QPM) на вызовы Externaltransactions.createexternaltransaction или Externaltransactions.refundexternaltransaction . Вызовы Externaltransactions.getexternaltransaction не учитываются в этом пределе в 1200 QPM.