Ако радите са куповинама у апликацији на Андроиду, пре или касније ћете морати да се суочите са Библиотека за обрачун Google Play-а, верзија 7То није само још једно ажурирање: долази са променама API-ја, новим функцијама претплате, захтевима за конзолу и веома јасним роковима од стране компаније Google. Игнорисање више није опција ако желите да наставите са објављивањем или ажурирањем апликације на Google Play-у без икаквих изненађења.
Кроз цео овај чланак видећете како Ажурирајте и имплементирајте Google Play Billing Library v7 Корак по корак: од онога што се разликује од PBL 5 и 6, до тога како интегрисати претплате, једнократне куповине, RTDN, тестирање са Play Billing Lab-ом и како преживети у екосистемима попут .NET MAUI-ја где званична подршка заостаје. Идеја је да, када завршите са читањем, можете припремити миграцију са поверењем и без трошења иједног динара.
Преглед библиотеке за обрачун Google Play верзије 7
Библиотека за плаћање Google Play 7 уводи значајна побољшања у начину управљања рачунима Плаћања, претплате и посебни плановиМеђутим, дизајниран је тако да миграција буде релативно глатка. Добра вест је да су многи нови API-ји опциони: можете ажурирати зависност, подесити неколико референци, а ваша основна интеграција ће и даље радити.
Ова верзија се фокусира на три кључне области: нове опције претплате (као што су виртуелне квоте), боља подршка за куповине на чекању на претплаћеним плановимаи измене API-ја које чисте оно што је већ било застарело у претходним верзијама (PBL 5 и 6). Поред тога, Google прилагођава неке начине обраде грешака и начин на који би требало да обрађујете трансакције на чекању како бисте избегли недоследности.
За почетак, у модулу ваше апликације потребно је да ажурирате зависност у датотеци буилд.градле:
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 Play-уКод претплата морате контролисати обнављања, грејс периоде, суспензије и отказивања како би корисник добио тачно оно што је платио, а не дан мање.
Интеграција у апликацију је само пола посла: ваш сервер мора да одржава поуздана евиденција права и статуса куповинеОво је посебно важно ако нудите приступ више платформи или вам је потребна детаљна статистика о приходима, задржавању и одливу корисника. Ту долазе до изражаја обавештења за програмере у реалном времену (RTDN), која делују као „црна кутија“ животног циклуса куповине.
Са RTDN-ом можете реаговати готово у реалном времену на критичне догађаје: нову куповину, неуспешно обнављање, претплату која улази у грејс период или отказану куповину. Ово вам омогућава да развијете стратегије за опоравак претплатника и превенција превара, као што је аутоматско слање имејла када плаћање не успе или прилагођавање права ако купац не прими поруку због проблема са мрежом.
Обавештења за програмере у реалном времену (RTDN) и Google Cloud Pub/Sub
RTDN-ови користе Гоогле Цлоуд Пуб/Суб као систем за размену порука у реалном времену између 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
}
Захваљујући овим порукама можете Синхронизујте свој бекенд чак и ако уређај корисника откажеЗамислите да корисник успешно обави куповину, Google Play то потврђује, али мобилни уређај губи везу пре него што ваша апликација прими повратни позив из Billing Library. Без RTDN-а, можда никада нећете знати. Са Pub/Sub, ваш сервер добија посебно обавештење и може да додели овлашћење независно од клијента.
Конфигурација Cloud Pub/Sub-а за RTDN
Пре него што активирате RTDN у Google Play конзоли, потребно је да припремите пројекат у Гоогле Цлоуд Платформ (ГЦП) и тамо конфигуришите Pub/Sub. Процес је релативно једноставан, али је најбоље пажљиво га пратити како бисте избегли изненађења са дозволама или називима ресурса.
Креирање теме
Прво морате да креирате Тема публикације/претплате који ће служити као тачка објављивања на Google Play-у. Из Google Cloud конзоле изаберите свој пројекат, идите на одељак Pub/Sub и креирајте нову тему пратећи званични водич за „креирање теме“. Резултат ће имати име у следећем формату:
projects/{project_id}/topics/{topic_name}
То пуно име је оно које ћете морати да налепите у Play Console када активирате обавештења.
Креирање претплате
Да бисте прочитали поруке у овој теми, потребан вам је Претплата на паб/сабМожете га конфигурисати као гурати или као повућиУ референтној лабораторији за кодирање, радимо са претплатом на повлачење, где ваш бекенд иницира захтеве за преузимање порука.
Требало би да прегледате опције у водичу за претплатнике на Cloud Pub/Sub како бисте одлучили да ли је push или pull боље решење за вашу архитектуру. Када се одлучите, пратите документацију за „додавање претплате“ и повежите је са темом коју сте раније креирали. Од тог тренутка, све поруке које Google Play објави у теми биће доступне вашем претплатнику.
Дозволе за објављивање у вашој теми са Google Play-а
Pub/Sub неће дозволити Google Play-у да објави било шта осим ако му не дате експлицитну дозволу. налог за услугуУ конзоли Google Cloud, потребно је да одете на подешавања дозвола за тему и додате главну:
[email protected]
Додели овом налогу улогу Издавач пабова/претплатничких услуга (Издавач). Сачувајте измене и од тог тренутка ће Google Play моћи да шаље RTDN-ове вашој теми без проблема са ауторизацијом.
Активирајте RTDN у Google Play конзоли
Када је 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 у вашем бекенду
Када су тема и претплата спремни, време је за имплементацију претплатник који чита и обрађује RTDN-овеГугл пружа примере на неколико језика; типичан случај у Јави користи клијентске библиотеке Cloud Pub/Sub за покретање Subscriber који слуша поруке и позива MessageReceiver.
Општи образац је увек исти: преузмете поруку, декодирате поље data Конвертујете base64 у текст, анализирате JSON и издвајате релевантна поља (као што су packageName, oneTimeProductNotification o subscriptionNotification) и одлучите шта да урадите у свом систему. Након успешне обраде обавештења, морате Потврдите поруку потврдом тако да га Pub/Sub не шаље поново.
Пример кода показује како пријемник исписује верзију и име пакета, али у стварној имплементацији бисте ишли даље: Потврдили бисте куповину, дајући право исправном корисникуАжурирали бисте базу података и, ако је потребно, позвали Play Developer API да бисте конзумирали или препознали куповину.
Повежи обавештења са корисником: коришћењем obfuscatedAccountId-а
Уобичајени проблем при управљању куповинама са сервера је сазнање ком кориснику припада одређено RTDN обавештење. За ово, Billing Client API вам омогућава да приложите замаскирани идентификатор налога када покренете процес куповине: obfuscatedAccountId.
Идеја је да користите стабилан идентификатор из вашег система (на пример, интерни ИД корисника), али замагљено због разлога приватности и безбедностиОва вредност је повезана са куповином, а затим се појављује у информацијама које враћа Google Play Developer API, тако да када примите RTDN и верификујете токен, недвосмислено ћете знати ком налогу у вашој бази података треба да доделите право.
Са стране купца, приликом припреме BillingFlowParamsСамо треба да направите листу ProductDetailsParams и позовите setObfuscatedAccountId(obfuscatedAccountId) пре покретања тока. То не мења видљиво корисничко искуство, али знатно поједностављује процес. Логика расподеле куповине на серверу и помаже Гуглу да открије превару.
Верификујте куповине помоћу Google Play Developer API-ја
Пре него што доделите било каква права на вашем серверу, обавезно је проверити да ли је куповина легитимна позивањем API за програмере на Google Play-уНије довољно ослањати се на оно што клијент или чак RTDN каже: морате потврдити purchaseToken директно према званичним крајњим тачкама, и ако је потребно управљање повраћајима новца.
У случају јединствених производа, користићете крајњу тачку purchases.products:getЗа претплате, пут води кроз purchases.subscriptionsv2:getПрепоручени ток је:
- Издвојите
purchaseTokenиз поруке „Pub/Sub“. - Проверите своју базу података да видите да ли сте је већ обрадили; сваки токен је глобално јединственДакле, савршен је као примарни кључ да би се избегли дупликати.
- Ако је нов, позовите Google Play Developer API са пакетом, SKU-ом и
purchaseToken. - Проверите да ли одговор указује на статус куповине КУПИО (није НА ЧЕКАЊУ нити отказано).
- Ако се све поклапа, региструјте токен и доделите одговарајуће право придруженом кориснику.
Да бисте комуницирали са Play Developer API-јем из Јаве, можете користити 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 Billing Library“ и изаберите које кодове грешака желите да вратите за сваки 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Према самом Гуглу, то је у основи промена имена без промена у понашању, у контексту обележеном споразумима као што су Гугл и Епик Гејмс се договорили да отворе Андроид.
Коначно, уноси се нови код грешке. ГРЕШКА_У_МРЕЖИ en BillingResultи значења и услови SERVICE_TIMEOUT и SERVICE_UNAVAILABLEАко имате прилагођену логику за руковање грешкама (на пример, одлучивање када да се кориснику прикаже порука, када да се тихо поново покуша итд.), препоручљиво је да је прегледате како бисте узели у обзир ове нове нијансе.
Трансакције на чекању и одсуство ИД-а поруџбине до КУПОВИНЕ
Суптилна промена у PBL 7 је да библиотека више не генерише ИД поруџбине за куповине на чекању. У овим случајевима, orderId Биће доступно тек када куповина достигне статус КУПЉЕНО. Ово посебно утиче на токове рада где сте од почетка користили ИД поруџбине као примарну референцу.
Гуглова препорука је да се ослоните на purchaseToken за ваше евиденције и помирењабарем док је трансакција на чекању. Ако пронађете куповину која је нестала са Play-а, проверите Шта урадити ако куповина нестане.
Ако још нисте радили са неизмиреним дуговима, прегледајте водич за интеграцију библиотеке за обрачун и документацију о управљање животним циклусом набавкеТамо ћете пронаћи различита стања, како реаговати на свако од њих и како се RTDN-ови уклапају у ову слагалицу.
Нове опционе могућности у PBL 7: виртуелне рате и претплате
Међу „лепим“ новим карактеристикама PBL 7 су виртуелне претплате (виртуелне претплате на рате) и проширена подршка за куповине на чекању за претплате. Ове функције нису обавезне, али вам могу пружити већу флексибилност приликом прилагођавања вашег пословног модела различитим тржиштима.
Виртуелне рате омогућавају кориснику да плати за дугорочнију претплату у мале периодичне уплатеУместо једне велике уплате, Гугл објашњава да, у сврху наплате програмерима, настављате да примате месечне уплате у оквиру годишњег плана са месечним ратама. Ако корисник пропусти уплату, ни ви ни Гугл не би требало да покушавате да надокнадите прошле рате. Због тога је његова практична употреба прилично слична стандардној месечној претплати, барем у почетку.
За сада, ове претплате су доступне само у Бразил, Француска, Италија и ШпанијаГугл препоручује да пратите Play конзолу за земље које су недавно подржане. Конфигурација се врши путем ProductDetails.InstallmentPlanDetails и пратећи посебан водич да бисте их интегрисали у своју апликацију.
Паралелно, подршка се проширује куповине на чекању за претплатеСада можете понудити моделе где корисник започиње куповину у апликацији и касније завршава плаћање на друге начине, а Библиотека за наплату зна како да правилно обради тај ток. Активација се врши позивањем функције enablePendingPurchases() приликом иницијализације BillingClient-а и, посебно за претплаћене планове, користећи PendingPurchasesParams.Builder.enablePrepaidPlans().
Периоди амортизације за Play Billing Library 5 и 6
Са PBL 7 на сцени, Google је одредио јасне датуме за повлачење подршке за верзије 5 и 6Ако сте још увек у неком од њих, морате означити календар црвеном бојом:
- Google Play Billing Library 5 ће званично бити застарео 31. августа 2024. године за нове апликације и ажурирања. Могуће је затражити продужење до 1. новембра 2024. године, али то није нешто на шта би требало да се ослањате дугорочно.
- Библиотека за обрачун Google Play верзије 6 може се користити за објављивање нових апликација до 1. августа 2025. године и за ажурирање постојећих апликација до 1. новембра 2025. године.
Након тог датума, ако нисте мигрирали барем на верзију 6 или идеално на верзију 7, мораћете да ажурирате на најновију верзију. Верзија КСНУМКСАжурирања ће бити блокирана у Play конзоли. Иако ће ваша апликација наставити да функционише на уређајима корисника, бићете замрзнути, нећете моћи да исправљате грешке или додајете нове функције које зависе од објављивања у продавници.
Случај .NET MAUI-ја и тренутна ограничења
Ако радите са .NET MAUI-јем и претплатама на Андроиду, вероватно сте већ прочитали или искусили да то није тако једноставно. Многи пројекти су користили Plugin.InAppBilling од стране Џејмса Монтемањоа, али је додатак архивиран и неодржаван, тако да неће бити ажуриран да би подржао Billing Library 7. Истовремено, званични пакет Xamarin.Android.Google.BillingClient Остао је везан за екосистем Xamarin.Android и није директно компатибилан са .NET MAUI.
Практична последица је да је Упозорења Play конзоле Ваша апликација не користи 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-ја, јачање бекенд логике помоћу верификације куповине и RTDN-а, као и коришћење алата за тестирање попут Play Billing Lab-а како би се откриле све грешке пре објављивања. Они који одвоје време за фино подешавање ове миграције биће у могућности да се боље носе са претплаћеним плановима, виртуелним накнадама, мрежним грешкама и променама животног циклуса претплате, и имаће много веће шансе да одрже стабилан приход и углађено корисничко искуство на Google Play-у. Поделите информације како би више корисника могло да сазна више о теми.