Ако работите с покупки в приложението на Android, рано или късно ще се наложи да се справите с... Библиотека за фактуриране в Google Play, версия 7Това не е просто поредната актуализация: тя идва с промени в API, нови функции за абонамент, изисквания за конзолата и много ясни срокове от Google. Пренебрегването ѝ вече не е опция, ако искате да продължите да публикувате или актуализирате приложението си в Google Play без никакви изненади.
В цялата тази статия ще видите как Актуализирайте и внедрете библиотеката за фактуриране в Google Play v7 Стъпка по стъпка: от това какво е различното от PBL 5 и 6, до това как да интегрирате абонаменти, еднократни покупки, RTDN, тестване с Play Billing Lab и как да оцелеете в екосистеми като .NET MAUI, където официалната поддръжка изостава. Идеята е, че когато приключите с четенето, можете да подготвите миграцията си с увереност и без да харчите нито стотинка.
Общ преглед на библиотеката за фактуриране в Google Play, версия 7
Библиотеката за фактуриране на Google Play 7 въвежда значителни подобрения в начина на управление на сметките. Плащания, абонаменти и специални плановеВъпреки това, той е проектиран така, че миграцията да е сравнително плавна. Добрата новина е, че много от новите API са опционални: можете да актуализирате зависимостта, да промените няколко препратки и основната ви интеграция ще продължи да работи.
Тази версия се фокусира върху три ключови области: нови опции за абонамент (като виртуални квоти), по-добра поддръжка за чакащи покупки по предплатени плановеи промени в API, които премахват това, което вече е било остаряло в предишни версии (PBL 5 и 6). Освен това Google коригира някои методи за обработка на грешки и начина, по който трябва да се обработват чакащи транзакции, за да се избегнат несъответствия.
За начало, в модула на приложението ви трябва да актуализирате зависимостта във файла си build.gradle:
dependencies {
def billingVersion = "7.0.0"
implementation "com.android.billingclient:billing:$billingVersion"
}
След като това е направено, е време да прегледаме кода, който използва стари API. Много извиквания, свързани с пропорционално разпределение на абонамента и алтернативно фактуриране Те са преименувани или премахнати, така че е добра идея да разгледате добре всички препратки към BillingClient и BillingFlowParams, преди да компилирате и качите каквото и да било в Play Console.
Стратегии за монетизация с еднократни покупки и абонаменти
Когато продавате дигитални продукти в приложението си, простото поставяне на диалоговия прозорец за покупка и приключването на процеса не е достатъчно: проектирането на безпроблемно потребителско изживяване през целия цикъл на покупкаТова важи както за единични продукти (консумируеми или неконсумируеми), така и за абонаменти. Колкото по-естествен и безпроблемен е процесът, толкова по-високи са реализациите и по-нисък е процентът на анулиране.
Типичният процес на покупка с Play Billing, независимо дали става въпрос за абонамент или за единичен артикул, обикновено следва тези добре дефинирани етапи, за които вашият бекенд също трябва да е наясно:
- Потребителят разглежда наличните продукти и избира един от тях.
- Приложението инициира процеса на фактуриране в Google Play, за да завърши плащането.
- Покупката е завършена и приложението ви получава резултата.
- Вашият сървър валидира покупката спрямо Google Play Developer API.
- Съответното съдържание или право се предоставя на потребителя във вашата система.
- Google е информиран, че покупката е обработена (изпълнена или потвърдена).
В случай на консумативи, е изключително важно консумирайте токена в точното време да се осигури безпроблемно повторно закупуване и помощ Блокиране на случайни покупки в Google PlayПри абонаментите трябва да контролирате подновяванията, гратисните периоди, спиранията и анулиранията, така че потребителят да получава точно това, за което е платил, и нито ден по-малко.
Интеграцията в приложението е само половината от работата: вашият сървър трябва да поддържа надежден запис на правата и статуса на покупкитеТова е особено важно, ако предлагате междуплатформен достъп или се нуждаете от подробна статистика за приходи, задържане и отлив на клиенти. Тук се намесват известията за разработчици в реално време (RTDN), действащи като „черна кутия“ на жизнения цикъл на покупката.
С RTDN можете да реагирате почти в реално време на критични събития: нова покупка, неуспешно подновяване, абонамент, навлизащ в гратисен период, или анулирана покупка. Това ви позволява да разработвате стратегии за възстановяване на абонатите и предотвратяване на измами, като например автоматично изпращане на имейл при неуспешно плащане или корекции на правата, ако клиентът не получи съобщението поради мрежови проблеми.
Известия за разработчици в реално време (RTDN) и Google Cloud Pub/Sub
RTDN използват Google Cloud Pub/Sub като система за съобщения в реално време между Google Play и вашия бекенд. Google Play публикува събития по тема от Pub/Sub, а вие се абонирате за тази тема, за да получавате съобщения всеки път, когато състоянието на покупка или абонамент се промени.
Основният процес е прост: Google Play изпраща съобщение, кодирано с base64, до темата Pub/Sub, вашият абонат го извлича, декодира и обработва известието. В полето data В съобщението ще намерите JSON обект Известие за разработчицикоето включва информация като версия на съобщението, име на пакета, час на събитието и специфични данни за еднократни покупки, абонаменти, анулирани покупки или пробни периоди.
{
"version": string,
"packageName": string,
"eventTimeMillis": long,
"oneTimeProductNotification": OneTimeProductNotification,
"subscriptionNotification": SubscriptionNotification,
"voidedPurchaseNotification": VoidedPurchaseNotification,
"testNotification": TestNotification
}
Благодарение на тези съобщения можете Поддържайте backend синхронизиран, дори ако устройството на потребителя се повредиПредставете си, че потребител успешно прави покупка, Google Play я потвърждава, но мобилното устройство губи връзка, преди приложението ви да получи обратното извикване от библиотеката за фактуриране. Без RTDN може никога да не разберете. С Pub/Sub вашият сървър получава отделно известие и може да предостави правото независимо от клиента.
Конфигурация на Cloud Pub/Sub за RTDN
Преди да активирате RTDN в конзолата на Google Play, трябва да подготвите проект в Google Cloud Platform (GCP) и конфигурирайте Pub/Sub там. Процесът е сравнително лесен, но е най-добре да го следвате внимателно, за да избегнете изненади с разрешения или имена на ресурси.
Създаване на темата
Първо трябва да създадете Тема за публикация/подпис който ще действа като вашата точка за публикуване в Google Play. От конзолата на Google Cloud изберете проекта си, отидете в секцията „Публикация/Абонентска публикация“ и създайте нова тема, следвайки официалното ръководство за „създаване на тема“. Резултатът ще има име в следния формат:
projects/{project_id}/topics/{topic_name}
Това пълно име е това, което ще трябва да поставите в Play Console, когато активирате известията.
Създаване на абонамент
За да прочетете съобщенията в тази тема, ви е необходим Абонамент за Pub/SubМожете да го конфигурирате като тласък или като издърпайтеВ референтната кодова лаборатория работим с pull абонамент, където вашият backend инициира заявките за извличане на съобщения.
Трябва да прегледате опциите в ръководството за абонати на Cloud Pub/Sub, за да решите дали push или pull е по-подходящ за вашата архитектура. След като вземете решение, следвайте документацията за „добавяне на абонамент“ и го свържете с темата, която създадохте по-рано. От този момент нататък всички съобщения, публикувани от Google Play в темата, ще бъдат достъпни за вашия абонат.
Разрешения за публикуване в Google Play по вашата тема
Pub/Sub няма да позволи на Google Play да публикува каквото и да било, освен ако не му дадете изрично разрешение. акаунт за услугиВ конзолата на Google Cloud трябва да отидете в настройките за разрешения на темата и да добавите основната:
[email protected]
Дайте на този акаунт ролята на Издател на Pub/Sub (Издател). Запазете промените и от този момент нататък Google Play ще може да изпраща RTDN-и към вашата тема без проблеми с оторизацията.
Активирайте RTDN в Google Play Console
След като Pub/Sub е конфигуриран, трябва да кажете на Play Console къде да се изпращат известия. В приложението си в Google Play Console отидете на Монетизация с Play > Настройки за монетизация и намерете секцията за известия за разработчици в реално време.
Там ще ви е необходимо:
- Поставете отметка в квадратчето, за да активирате известията в реално време.
- Въведете пълното име на темата за публикация/подпис в съответното поле, спазвайки формата
projects/{project_id}/topics/{topic_name}. - Изпратете тестово съобщение, като използвате бутона за тест.
Тестовото съобщение е от съществено значение, за да се провери дали Интеграцията е добре реализирана.Ако имате абонамент за изтегляне, можете да отидете в конзолата на Cloud, да изберете абонамента, да кликнете върху „Преглед на съобщенията“ и да извлечете тестовото съобщение. Не забравяйте да направите АСК на всяко съобщение, което четете, за да избегнете повторно получаване.
За push абонаменти, проверете дали вашата крайна точка получава съобщението и отговаря с валиден HTTP код. Ако нещо се обърка, конзолата ще покаже грешка при публикуване на теста, обикновено свързана с името на темата или разрешенията на сервизния акаунт.
Накрая можете да конфигурирате какви видове известия искате да получавате: само абонаменти и анулирани покупки или всички известия, включително еднократни покупки (събития като ONE_TIME_PRODUCT_PURCHASED и ONE_TIME_PRODUCT_CANCELED). Ако използвате и уникални продукти, обичайна практика е да активирате целия набор, за да се поддържа видимост на всичко.
Създайте абонат за Pub/Sub във вашия backend
След като темата и абонаментът са готови, е време да внедрите абонат, който чете и обработва RTDNGoogle предоставя примери на няколко езика; типичен случай в Java използва клиентските библиотеки на Cloud Pub/Sub за стартиране на Subscriber който слуша съобщения и се обажда MessageReceiver.
Общият модел е винаги един и същ: извличате съобщението, декодирате полето data Конвертирате base64 в текст, анализирате JSON и извличате съответните полета (като например packageName, oneTimeProductNotification o subscriptionNotification) и решете какво да направите във вашата система. След успешна обработка на известието, трябва Потвърдете съобщението с потвърждение така че Pub/Sub да не го изпраща отново.
Примерният код показва как приемникът отпечатва версията и името на пакета, но в реална имплементация бихте отишли по-далеч: Вие бихте валидирали покупката, предоставяйки правото на правилния потребителЩе актуализирате базата си данни и, ако е необходимо, ще извикате Play Developer API, за да консумирате или разпознаете покупката.
Свързване на известия към потребителя: използване на obfuscatedAccountId
Често срещан проблем при управлението на покупки от сървъра е да се знае на кой потребител принадлежи конкретно RTDN известие. За тази цел API на клиента за фактуриране ви позволява да прикачите обфускиран идентификатор на акаунт когато стартирате процеса на покупка: obfuscatedAccountId.
Идеята е да използвате стабилен идентификатор от вашата система (например вътрешния идентификатор на потребителя), но обфускирано от съображения за поверителност и сигурностТази стойност се свързва с покупката и след това се показва в информацията, върната от Google Play Developer API, така че когато получите RTDN и проверите токена, ще знаете недвусмислено на кой акаунт във вашата база данни трябва да предоставите правото.
От страна на клиента, при подготовката на BillingFlowParamsПросто трябва да съставите списъка с ProductDetailsParams и се обадете setObfuscatedAccountId(obfuscatedAccountId) преди стартиране на потока. Това не променя видимото потребителско изживяване, но значително опростява процеса. Логика за разпределение на покупките от бекенд системата и помага на Google да открива измами.
Проверка на покупките чрез API за разработчици на Google Play
Преди да предоставите каквито и да е права на вашия сървър, е задължително да проверите дали покупката е легитимна, като се обадите на API за разработчици на Google PlayНе е достатъчно да разчитате на това, което казва клиентът или дори RTDN: трябва да валидирате purchaseToken директно срещу официалните крайни точки и ако е необходимо управление на възстановяванията на суми.
В случай на уникални продукти, ще използвате крайната точка purchases.products:getЗа абонаментите пътят води през purchases.subscriptionsv2:getПрепоръчителният поток е:
- Извадете
purchaseTokenот съобщението Pub/Sub. - Проверете базата си данни, за да видите дали вече сте я обработили; всеки токен е уникален в световен мащабТака че е идеален като първичен ключ, за да се избегнат дубликати.
- Ако е нов, извикайте API за разработчици на Google Play с пакета, SKU и
purchaseToken. - Проверете дали отговорът показва състояние на покупка ЗАКУПЕН (не е В ИЗЧАКВАНЕ или отменено).
- Ако всичко съвпада, регистрирайте токена и предоставете съответното право на свързания потребител.
За да комуникирате с Play Developer API от Java, можете да използвате AndroidPublisher, инициализиран с идентификационни данни за сервизен акаунт във формат JSON. Вие конфигурирате обхвата AndroidPublisherScopes.ANDROIDPUBLISHERСъздавате клиента и извиквате метода purchases().products().get(...)Ако обаждането не успее поради временен проблем с мрежата или услугата, препоръчително е внедрете повторни опити с експоненциално отсрочване за да не пропуснете събитието.
Потвърдете или завършете покупката от сървъра
След като потвърдите покупката и предоставите оторизацията в системата си, следващата стъпка е да уведомите Google, че транзакцията е обработена успешно. За продукти с един артикул имате две възможности: консумирайте покупката или просто разпознай я.
Консумативните продукти (напр. виртуална валута, животи и др.) трябва да преминат през крайната точка purchases.products:consumeТова маркира токена като използван и позволява на потребителя да закупи отново същия артикул без конфликт. За продукти, които не се консумират (като например отключване на премиум версията за цял живот), трябва да се обадите на purchases.products:acknowledge, което информира Google, че потребителят вече има съответното право.
Абонаментите се използват purchases.subscriptions:acknowledgeкоето показва, че абонаментът е успешно обработен и прехвърлен на потребителя. Ако не потвърдите покупка в разумен срок, Google може да предположи, че има проблем и да отмени транзакцията, така че е важно да обратното се извършва веднага след предоставяне на правото.
В помощника на AndroidPublisher можете да добавяте методи като executeProductPurchasesConsume y executeProductPurchasesAcknowledge които извикват съответните крайни точки. Отново е препоръчително да се внедрят повторни опити в случай на случайни неуспехи, за да се гарантира, че нито един токен не остава в опасно междинно състояние.
Разширено тестване с Play Billing Lab
Един аспект, който много разработчици подценяват, е фазата на тестване. За да стартирате с каквато и да е степен на увереност, трябва да можете да симулирате мрежови грешки, нестандартни отговори и гранични случаиЕто къде се намесва Play Billing Lab, безплатно приложение в Google Play, създадено специално за тестване на интеграции с Play Billing Library.
Лабораторията за фактуриране в Play включва симулатор на отговори което позволява форсирането на различни BillingResponseCode в извикванията на приложението ви към библиотеката за фактуриране. По този начин можете да пресъздадете сценарии, при които например клиентът не може да завърши покупката поради проблем с мрежата, но вашият бекенд правилно обработва RTDN и в крайна сметка предоставя правото без намеса на потребителя.
За да може приложението ви да комуникира със симулатора, трябва да активирате тестването на „преотмяна на фактурирането“, използвайки метаданни в AndroidManifest.xml:
<manifest ... >
<application ... >
...
<meta-data
android:name="com.google.android.play.largest_release_audience.NONPRODUCTION"
android:value="" />
<meta-data
android:name="com.google.android.play.billingclient.enableBillingOverridesTesting"
android:value="true" />
</application>
</manifest>
Етикетът активиране на тестването на пренаписване на фактурирането Активирайте симулираните тестове за отговор в библиотеката за фактуриране. Тагът NONPRODUCTION е вид напомняне, че тази компилация не трябва да влиза в производство с активни презаписвания. Когато подготвяте финалната версия за потребителите, не забравяйте да Премахнете тези метаданни или използвайте отделен манифест.
След като конфигурирате, от приложението Play Billing Lab влезте с акаунт на тестер на лицензи, активирайте опцията „Симулиране на отговора на библиотеката за фактуриране на Play“ и изберете кои кодове за грешки искате да върнете за всеки API (например конкретна грешка в consumeAsyncСлед това просто отваряте приложението си и изпълнявате потока, който искате да тествате: симулаторът ще върне конфигурираните отговори и можете да проверите дали логиката за повторен опит, обработката на грешки и RTDN се държат според очакванията.
Ключови промени в API при мигриране към Play Billing Library 7
Освен RTDN и тестването, мигрирането към PBL 7 включва обръщане на внимание на някои специфични API точки. За тези, които преминават от PBL 5 или 6, си струва да прегледат най-важните промени, за да се гарантира, че проектът се компилира гладко и бизнес логиката остава последователна.
Първо, API-тата, свързани с Пропорционален режим Опциите за промяна на абонамента са премахнати. Сега се използва следното: Режим на замяна за управление на промените в плана (надстройки, понижавания и др.). Ако все още използвате методи като setReplaceProrationMode o setReplaceSkusProrationModeЩе трябва да ги мигрирате към новите варианти на setSubscriptionReplacementMode и коригирайте логиката съгласно актуализираната документация.
API също е премахнат launchPriceConfirmationFlowкоето вече беше маркирано като остаряло. За да се справите с промените в цените на абонамента, трябва да се обърнете към новите работни процеси и препоръки в ръководството за промяна на цените, което подробно описва как правилно да информирате потребителя и как да управлявате съгласието.
Друг важен момент е Алтернативни API за фактуриранеМетодите BillingClient.Builder.enableAlternativeBilling, AlternativeBillingListener y AlternativeChoiceDetails са изчезнали в полза на по-съгласувана номенклатура: сега трябва да използвате BillingClient.Builder.enableUserChoiceBilling() до UserChoiceBillingListener y UserChoiceDetailsСпоред самия Google, това е основно промяна на името без промени в поведението, в контекст, белязан от споразумения като Google и Epic Games се споразумяват да отворят Android.
Накрая се въвежда нов код за грешка. МРЕЖОВА_ГРЕШКА en BillingResultи значенията и условията на SERVICE_TIMEOUT и SERVICE_UNAVAILABLEАко имате персонализирана логика за обработка на грешки (например, решаване кога да се покаже съобщение на потребителя, кога да се направи тих повторен опит и т.н.), препоръчително е да я прегледате, за да вземете предвид тези нови нюанси.
Чакащи транзакции и липса на orderId до PURCHASED
Една фина промяна в PBL 7 е, че библиотеката вече не генерира Идентификационен номер на поръчката за чакащи покупки. В тези случаи, orderId Ще бъде налично само след като покупката достигне състояние „ЗАКУПЕНА“. Това се отнася особено за работни процеси, при които от самото начало сте използвали идентификационния номер на поръчката като основна референция.
Препоръката на Google е да разчитате на purchaseToken за вашите записи и съгласуванияпоне докато транзакцията е в процес на обработка. Ако откриете покупка, която е изчезнала от Play, проверете Какво да направите, ако покупката изчезне.
Ако все още не сте работили с непогасени салда, прегледайте ръководството за интеграция на Billing Library и документацията на управление на жизнения цикъл на обществените поръчкиТам ще намерите различните състояния, как да реагирате на всяко от тях и как RTDN се вписват в този пъзел.
Нови допълнителни възможности в PBL 7: виртуални вноски и предплащания
Сред „приятните“ нови функции на PBL 7 са абонаменти с виртуална такса (виртуални абонаменти на вноски) и разширена поддръжка за чакащи покупки за предплатени абонаменти. Тези функции не са задължителни, но могат да ви дадат по-голяма гъвкавост при адаптиране на вашия бизнес модел към различни пазари.
Виртуалните вноски позволяват на потребителя да плати за по-дълъг абонамент в малки периодични плащанияВместо еднократно голямо плащане, Google обяснява, че за целите на фактурирането на разработчиците, вие продължавате да получавате месечни плащания по годишен план с месечни вноски. Ако потребител пропусне плащане, нито вие, нито Google трябва да се опитвате да възстановите минали вноски. Това прави практическото му използване доста подобно на стандартен месечен абонамент, поне първоначално.
Засега тези абонаментни такси са налични само в Бразилия, Франция, Италия и ИспанияGoogle препоръчва да следите Play Console за новоподдържаните държави. Конфигурацията се извършва чрез ProductDetails.InstallmentPlanDetails и следвайки конкретното ръководство, за да ги интегрирате в приложението си.
Успоредно с това се разширява и подкрепата чакащи покупки за предплатени абонаментиСега можете да предлагате модели, при които потребителят започва покупката в приложението и завършва плащането по-късно чрез други средства, а библиотеката за фактуриране знае как да обработи правилно този процес. Активирането се извършва чрез извикване на enablePendingPurchases() при инициализиране на BillingClient и, по-специално за предплатени планове, използвайки PendingPurchasesParams.Builder.enablePrepaidPlans().
Периоди на амортизация за библиотека 5 и 6 за фактуриране в Play
С PBL 7 на сцената, Google определи ясни дати за оттегляне на поддръжката за версии 5 и 6Ако все още сте в някой от тях, трябва да маркирате календара в червено:
- Библиотеката за фактуриране Google Play 5 ще бъде официално оттеглена на 31 август 2024 г. за нови приложения и актуализации. Възможно е да поискате удължаване до 1 ноември 2024 г., но това не е нещо, на което бива да разчитате в дългосрочен план.
- Библиотеката за фактуриране на Google Play версия 6 може да се използва за публикуване на нови приложения до 1 август 2025 г. и за актуализиране на съществуващи приложения до 1 ноември 2025 г.
След тази дата, ако не сте мигрирали поне към версия 6 или в идеалния случай към версия 7, ще трябва да актуализирате до най-новата версия. версия 7Актуализациите ви ще бъдат блокирани в Play Console. Въпреки че приложението ви ще продължи да функционира на устройствата на потребителите, ще бъде блокирано и няма да можете да поправяте грешки или да добавяте нови функции, които зависят от публикуването в магазина.
Случаят с .NET MAUI и текущите ограничения
Ако работите с .NET MAUI и абонаменти на Android, вероятно вече сте чели или сте се запознали с факта, че не е толкова просто. Много проекти използват Plugin.InAppBilling от Джеймс Монтеманьо, но плъгинът е архивиран и не се поддържа, така че няма да бъде актуализиран, за да поддържа Billing Library 7. В същото време, официалният пакет Xamarin.Android.Google.BillingClient Той остава свързан с екосистемата Xamarin.Android и не е директно съвместим с .NET MAUI.
Практическото следствие е, че Play Console предупреждава Приложението ви не използва Billing Library 7.0.0 или по-нова версия, което блокира актуализациите, ако продължите да използвате по-стари библиотеки. Някои разработчици са избрали драстични решения, като например временно деактивиране на абонаментите, за да могат да качват версии, но очевидно това не е устойчиво, ако вашият бизнес модел зависи от тази монетизация.
В този контекст много отбори обмислят алтернативи, като например SDK на трети страни Тези услуги вече поддържат PBL 7 и предоставят по-стабилен, междуплатформен API (например, решения за абонаментен бекенд с SDK за Android, iOS и други платформи). Тези услуги обикновено обработват миграциите на версиите на Billing Library и предоставят стабилна обвивка, което значително намалява натоварването с всяко ново отхвърляне на Google.
Докато Microsoft и екипът на MAUI не предложат Официалният пакет е актуализиран и напълно съвместим С Billing Library 7 опциите включват: внедряване на собствено обвързване с вградената Billing Library, използване на услуга на трета страна или преосмисляне на начина, по който интегрирате покупките в рамките на вашия MAUI проект. Във всеки случай е най-добре да не оставяте решението за последния момент, защото крайните срокове на Play са фиксирани.
Като цяло, актуализацията на Google Play Billing Library v7 включва преглед на зависимостите, почистване на остарели API, укрепване на логиката на backend-а с проверка на покупките и RTDN, както и използване на инструменти за тестване като Play Billing Lab за откриване на всички грешки преди пускането ѝ на пазара. Тези, които отделят време за фина настройка на тази миграция, ще могат по-добре да се справят с предплатени планове, виртуални такси, мрежови грешки и промени в жизнения цикъл на абонамента и ще имат много по-голям шанс да поддържат стабилни приходи и изпипано потребителско изживяване в Google Play. Споделете информацията, за да могат повече потребители да научат по темата.