Om du arbetar med köp i appar på Android kommer du förr eller senare att behöva hantera Google Play Faktureringsbibliotek v7Det är inte bara ytterligare en uppdatering: den kommer med API-ändringar, nya prenumerationsfunktioner, konsolkrav och mycket tydliga deadlines från Google. Att ignorera den är inte längre ett alternativ om du vill fortsätta publicera eller uppdatera din app på Google Play utan några överraskningar.
Genom hela den här artikeln kommer du att se hur Uppdatera och implementera Google Play Billing Library v7 Steg för steg: från vad som skiljer sig från PBL 5 och 6, till hur man integrerar prenumerationer, engångsköp, RTDN, testning med Play Billing Lab och hur man överlever i ekosystem som .NET MAUI där officiellt stöd släpar efter. Tanken är att när du har läst klart kan du förbereda din migrering med tillförsikt och utan att spendera ett öre.
Översikt över Google Play Faktureringsbibliotek v7
Google Play Billing Library 7 introducerar betydande förbättringar i hur fakturor hanteras Betalningar, prenumerationer och specialplanerDen är dock utformad för att göra migreringen relativt smidig. Den goda nyheten är att många av de nya API:erna är valfria: du kan uppdatera beroendet, justera några referenser, och din grundläggande integration kommer fortfarande att fungera.
Denna version fokuserar på tre huvudområden: nya prenumerationsalternativ (såsom virtuella kvoter), bättre stöd för väntande köp på förbetalda abonnemangoch API-ändringar som rensar upp det som redan var föråldrat i tidigare versioner (PBL 5 och 6). Dessutom justerar Google viss felhantering och hur du bör hantera väntande transaktioner för att undvika inkonsekvenser.
Till att börja med måste du uppdatera beroendet i din fil i din appmodul. bygga.gradle:
dependencies {
def billingVersion = "7.0.0"
implementation "com.android.billingclient:billing:$billingVersion"
}
När detta är klart är det dags att granska koden som använder äldre API:er. Många anrop relaterade till proportionell prenumeration och alternativ fakturering De har bytt namn eller tagits bort, så det är en bra idé att titta noga på alla referenser till BillingClient och BillingFlowParams innan du kompilerar och laddar upp något till Play Console.
Monetiseringsstrategier med engångsköp och prenumerationer
När du säljer digitala produkter i din app räcker det inte att bara klistra in köpdialogrutan och avsluta dagen: designa en sömlös användarupplevelse genom hela köpprocessenDetta gäller både enskilda produkter (förbrukningsbara eller icke-förbrukningsbara) och prenumerationer. Ju mer naturlig och friktionsfri processen är, desto högre konverteringar och desto lägre avbokningsfrekvens.
Ett typiskt köpflöde med Play Billing, oavsett om det gäller en prenumeration eller en enskild vara, följer vanligtvis dessa väldefinierade steg som din backend också bör vara medveten om:
- Användaren utforskar de tillgängliga produkterna och väljer en.
- Appen initierar Google Play-faktureringsprocessen för att slutföra betalningen.
- Köpet är slutfört och din app tar emot resultatet.
- Din server validerar köpet mot Google Play Developer API.
- Motsvarande innehåll eller rättighet beviljas användaren i ditt system.
- Google informeras om att köpet har behandlats (konsumerats eller bekräftats).
När det gäller konsumtionsvaror är det viktigt att konsumera token vid rätt tidpunkt för att möjliggöra smidiga återköp och hjälpa Blockera oavsiktliga köp på Google PlayI prenumerationer måste du kontrollera förnyelser, respitperioder, avstängningar och uppsägningar så att användaren får exakt vad de har betalat för och inte en dag mindre.
Integrering i appen är bara halva jobbet: din server måste upprätthålla en tillförlitlig registrering av rättigheter och köpstatusDetta är särskilt viktigt om du erbjuder åtkomst över flera plattformar eller behöver detaljerad statistik om intäkter, kundlojalitet och kundbortfall. Det är här utvecklarmeddelanden i realtid (RTDN) kommer in i bilden och fungerar som den "svarta lådan" i köpcykeln.
Med RTDN kan du reagera i nära realtid på kritiska händelser: ett nytt köp, en misslyckad förnyelse, en prenumeration som går in i sin respitperiod eller ett avbrutet köp. Detta gör att du kan utveckla strategier för återställning av prenumeranter och bedrägeriförebyggande, såsom automatisk e-postutskick när en betalning misslyckas eller justeringar av rättigheter om kunden inte får meddelandet på grund av nätverksproblem.
Realtidsmeddelanden för utvecklare (RTDN) och Google Cloud Pub/Sub
RTDN-användning Google Cloud Pub/Sub som ett realtidsmeddelandesystem mellan Google Play och din backend. Google Play publicerar händelser om ett Pub/Sub-ämne, och du prenumererar på det ämnet för att få meddelanden när statusen för ett köp eller en prenumeration ändras.
Grundflödet är enkelt: Google Play skickar ett base64-kodat meddelande till Pub/Sub-ämnet, din prenumerant extraherar det, avkodar det och bearbetar aviseringen. Inom fältet data Inuti meddelandet hittar du ett JSON-objekt Utvecklarmeddelandevilket inkluderar information som meddelandeversion, paketnamn, händelsetid och specifik data om engångsköp, prenumerationer, avbrutna köp eller provperioder.
{
"version": string,
"packageName": string,
"eventTimeMillis": long,
"oneTimeProductNotification": OneTimeProductNotification,
"subscriptionNotification": SubscriptionNotification,
"voidedPurchaseNotification": VoidedPurchaseNotification,
"testNotification": TestNotification
}
Tack vare dessa meddelanden kan du Håll din backend synkroniserad även om användarens enhet slutar fungeraTänk dig att en användare genomför ett köp, Google Play bekräftar det, men den mobila enheten förlorar anslutningen innan din app tar emot återuppringningen från faktureringsbiblioteket. Utan RTDN kanske du aldrig vet. Med Pub/Sub får din server en separat avisering och kan bevilja rättigheten oberoende av klienten.
Cloud Pub/Sub-konfiguration för RTDN
Innan du aktiverar RTDN i Google Play-konsolen måste du förbereda ett projekt i Google Cloud Platform (GCP) och konfigurera Pub/Sub där. Processen är relativt enkel, men det är bäst att följa den noggrant för att undvika överraskningar med behörigheter eller resursnamn.
Skapa ämnet
Först måste du skapa en Publicera/dela ämne vilket kommer att fungera som din publiceringspunkt för Google Play. Från Google Cloud-konsolen väljer du ditt projekt, går till avsnittet Publicera/Sub och skapar ett nytt ämne enligt den officiella guiden "skapa ämne". Resultatet kommer att ha ett namn i följande format:
projects/{project_id}/topics/{topic_name}
Det fullständiga namnet är det du måste klistra in i Play Console när du aktiverar aviseringar.
Skapande av prenumeration
För att läsa meddelandena i den här tråden behöver du en Pub/Sub-prenumerationDu kan konfigurera den som tryck eller som draI referenskodlabbet arbetar vi med pull-prenumeration, där din backend initierar förfrågningarna för att hämta meddelanden.
Du bör granska alternativen i prenumerationsguiden för Cloud Pub/Sub för att avgöra om push eller pull passar din arkitektur bättre. När du har bestämt dig följer du dokumentationen "Lägg till prenumeration" och länkar den till ämnet du skapade tidigare. Från och med då kommer alla meddelanden som Google Play publicerar i ämnet att vara tillgängliga för din prenumerant.
Behörigheter för Google Play att publicera till ditt tema
Pub/Sub tillåter inte Google Play att publicera något om du inte ger det uttryckligt tillstånd. servicekontoI Google Cloud-konsolen måste du gå till inställningarna för ämnesbehörigheter och lägga till huvudbehörigheten:
google-play-developer-notifications@system.gserviceaccount.com
Ge detta konto rollen som Pub/Sub-utgivare (Utgivare). Spara ändringarna och från och med det ögonblicket kommer Google Play att kunna skicka RTDN:er till ditt tema utan auktoriseringsproblem.
Aktivera RTDN i Google Play Console
När Pub/Sub har konfigurerats måste du ange i Play Console vart aviseringar ska skickas. Gå till i din app i Google Play Console. Tjäna pengar med Play > Inställningar för intäktsgenerering och leta reda på avsnittet för utvecklarmeddelanden i realtid.
Där behöver du:
- Markera rutan för att aktivera realtidsaviseringar.
- Ange det fullständiga Pub/Sub-ämnesnamnet i motsvarande fält, med hänsyn till formatet.
projects/{project_id}/topics/{topic_name}. - Skicka ett testmeddelande med testknappen.
Testmeddelandet är viktigt för att verifiera att Integrationen är väl implementerad.Om du har en pull-prenumeration kan du gå till molnkonsolen, välja prenumerationen, klicka på "Visa meddelanden" och extrahera testmeddelandet. Glöm inte att göra ack av alla meddelanden du läser för att undvika upprepade kvitton.
För push-prenumerationer, verifiera att din slutpunkt tar emot meddelandet och svarar med en giltig HTTP-kod. Om något går fel visar konsolen ett felmeddelande när testet publiceras, vanligtvis relaterat till ämnesnamnet eller behörigheterna för tjänstkontot.
Slutligen kan du konfigurera vilka typer av aviseringar du vill ta emot: endast prenumerationer och avbrutna köp, eller alla aviseringar inklusive engångsköp (händelser som ONE_TIME_PRODUCT_PURCHASED och ONE_TIME_PRODUCT_CANCELED). Om du också använder unika produkter är det vanligt att aktivera hela uppsättningen för att bibehålla synligheten över allt.
Bygg en Pub/Sub-prenumerant i din backend
Med temat och prenumerationen klara är det dags att implementera en abonnent som läser och bearbetar RTDN:erGoogle tillhandahåller exempel på flera språk; ett typiskt fall i Java använder Cloud Pub/Sub-klientbiblioteken för att starta en Subscriber som lyssnar på meddelanden och ringer MessageReceiver.
Det allmänna mönstret är alltid detsamma: du hämtar meddelandet, du avkodar fältet data Du konverterar base64 till text, analyserar JSON och extraherar relevanta fält (t.ex. packageName, oneTimeProductNotification o subscriptionNotification) och bestäm vad du ska göra i ditt system. Efter att meddelandet har bearbetats måste du Bekräfta meddelandet med en bekräftelse så att Pub/Sub inte skickar den igen.
Exempelkoden visar hur mottagaren skriver ut versionen och paketnamnet, men i en verklig implementering skulle man gå längre: Du skulle validera köpet och ge rätt användare rättighetenDu skulle uppdatera din databas och, om nödvändigt, anropa Play Developer API för att konsumera eller identifiera köpet.
Länka aviseringar till användaren: med hjälp av obfuscatedAccountId
Ett vanligt problem när man hanterar köp från servern är att veta vilken användare en specifik RTDN-avisering tillhör. För detta ändamål låter Billing Client API dig koppla en obfuskerad kontoidentifierare när du startar köpflödet: obfuscatedAccountId.
Tanken är att du använder en stabil identifierare från ditt system (till exempel användarens interna ID) men förvrängd av integritets- och säkerhetsskälDetta värde är kopplat till köpet och visas sedan i informationen som returneras från Google Play Developer API, så att när du tar emot RTDN och verifierar token, vet du otvetydigt vilket konto i din databas du ska bevilja rättigheten till.
På kundsidan, när man förbereder BillingFlowParamsDu behöver bara bygga upp listan ProductDetailsParams och ring setObfuscatedAccountId(obfuscatedAccountId) innan flödet startas. Det förändrar inte den synliga användarupplevelsen, men det förenklar processen avsevärt. backend-köpsallokeringslogik och hjälper Google att upptäcka bedrägerier.
Verifiera köp med Google Play Developer API
Innan du beviljar några rättigheter på din server är det obligatoriskt att verifiera att köpet är legitimt genom att anropa Google Play Developer APIDet räcker inte att lita på vad klienten eller ens RTDN säger: du måste validera purchaseToken direkt mot de officiella slutpunkterna, och om nödvändigt hantera återbetalningar.
När det gäller unika produkter använder du slutpunkten purchases.products:getFör prenumerationer går vägen genom purchases.subscriptionsv2:getDet rekommenderade flödet är:
- Extrahera
purchaseTokenfrån Pub/Sub-meddelandet. - Kontrollera din databas för att se om du redan har bearbetat den; varje token är globalt unikSå den är perfekt som en primärnyckel för att undvika dubbletter.
- Om det är nytt, anropa Google Play Developer API med paketet, SKU:n och
purchaseToken. - Kontrollera att svaret anger en köpstatus KÖPT (ej PÅGÅENDE eller avbruten).
- Om allt stämmer, registrera token och bevilja motsvarande rättighet till den associerade användaren.
För att kommunicera med Play Developer API från Java kan du använda Android-utgivare, initierad med tjänstkontouppgifter i JSON-format. Du konfigurerar omfånget AndroidPublisherScopes.ANDROIDPUBLISHERDu bygger klienten och anropar metoden purchases().products().get(...)Om samtalet misslyckas på grund av ett tillfälligt nätverks- eller tjänsteproblem rekommenderas det implementera återförsök med exponentiell backoff för att inte missa evenemanget.
Bekräfta eller slutför köpet från servern
När du har verifierat köpet och beviljat auktoriseringen i ditt system är nästa steg att meddela Google att transaktionen har behandlats. För produkter med en enda vara har du två alternativ: konsumera köpet eller bara känna igen henne.
Förbrukningsprodukter (t.ex. virtuell valuta, liv etc.) måste passera genom slutpunkten purchases.products:consumeDetta markerar token som använd och låter användaren köpa samma vara igen utan konflikt. För produkter som inte kan förbrukas (som att låsa upp premiumversionen på livstid) måste du ringa purchases.products:acknowledge, vilket informerar Google om att användaren redan har den tillhörande rättigheten.
Prenumerationer används purchases.subscriptions:acknowledgevilket indikerar att prenumerationen har behandlats och tilldelats användaren. Om du inte bekräftar ett köp inom rimlig tid kan Google anta att det finns ett problem och återkalla transaktionen, så det är viktigt att du tillbaka görs direkt efter att rätten beviljats.
I din AndroidPublisher-hjälp kan du lägga till metoder som executeProductPurchasesConsume y executeProductPurchasesAcknowledge som anropar motsvarande slutpunkter. Återigen är det lämpligt att implementera återförsök vid tillfälliga fel, för att säkerställa att ingen token förblir i ett farligt mellanliggande tillstånd.
Avancerad testning med Play Billing Lab
En aspekt som många utvecklare underskattar är testfasen. För att kunna lansera med någon grad av säkerhet måste man kunna simulera nätverksfel, icke-standardiserade svar och edge-fallDet är där Play Billing Lab kommer in i bilden, en gratisapp på Google Play som är speciellt utformad för att testa integrationer med Play Billing Library.
Play Billing Lab inkluderar en svarsimulator vilket möjliggör framtvingning av olika BillingResponseCode i din apps anrop till faktureringsbiblioteket. På så sätt kan du återskapa scenarier där kunden till exempel inte kan slutföra köpet på grund av ett nätverksproblem, men din backend bearbetar RTDN korrekt och slutligen beviljar rättigheten utan användarintervention.
För att din app ska kunna kommunicera med simulatorn måste du aktivera testning av "faktureringsåsidosättningar" med hjälp av metadata i 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>
Etiketten aktiveraFaktureringsöverskridandenTesting Aktivera de simulerade svarstesterna i faktureringsbiblioteket. NONPRODUCTION-taggen är en sorts påminnelse om att den här versionen inte ska gå i produktion med aktiva åsidosättningar. När du förbereder den slutliga versionen för användare, se till att Ta bort dessa metadata eller använd ett separat manifest.
När den är konfigurerad loggar du in med ett licenstestarkonto från Play Billing Lab-appen, aktiverar alternativet "Simulera svar från Play Billing Library" och väljer vilka felkoder du vill returnera för varje API (till exempel ett specifikt fel i consumeAsyncSedan öppnar du helt enkelt din app och kör det flöde du vill testa: simulatorn returnerar de konfigurerade svaren och du kan verifiera att din återförsökslogik, felhantering och RTDN beter sig som förväntat.
Viktiga API-ändringar vid migrering till Play Billing Library 7
Utöver RTDN och testning innebär migrering till PBL 7 att man tar itu med vissa specifika API-punkter. För de som kommer från PBL 5 eller 6 är det värt att granska de mest relevanta ändringarna för att säkerställa att projektet kompileras smidigt och att affärslogiken förblir konsekvent.
Först, API:erna relaterade till Prorationellt läge Alternativen för att ändra prenumerationen har tagits bort. Nu används följande: Ersättningsläge för att hantera planändringar (uppgraderingar, nedgraderingar etc.). Om du fortfarande använder metoder som setReplaceProrationMode o setReplaceSkusProrationModeDu måste migrera dem till de nya varianterna av setSubscriptionReplacementMode och justera logiken enligt den uppdaterade dokumentationen.
API:et har också tagits bort launchPriceConfirmationFlowvilket redan var markerat som föråldrat. För att hantera ändringar av prenumerationspriser bör du läsa de nya arbetsflödena och rekommendationerna i guiden för prisändringar, som beskriver hur du informerar användaren korrekt och hur du hanterar samtycke.
En annan viktig punkt är Alternativa fakturerings-API:erMetoderna BillingClient.Builder.enableAlternativeBilling, AlternativeBillingListener y AlternativeChoiceDetails har försvunnit till förmån för en mer anpassad nomenklatur: nu måste du använda BillingClient.Builder.enableUserChoiceBilling() bredvid UserChoiceBillingListener y UserChoiceDetailsEnligt Google själva är det i grunden ett namnbyte utan beteendeförändringar, i ett sammanhang präglat av avtal som t.ex. Google och Epic Games överens om att öppna upp Android.
Slutligen anges en ny felkod. NÄTVERKSFEL en BillingResultoch betydelserna och villkoren för SERVICE_TIMEOUT och SERVICE_UNAVAILABLEOm du har anpassad felhanteringslogik (till exempel för att bestämma när ett meddelande ska visas för användaren, när det ska försöka igen i tysthet osv.) är det lämpligt att granska den för att ta hänsyn till dessa nya nyanser.
Väntande transaktioner och avsaknad av order-ID fram till KÖP
En subtil förändring i PBL 7 är att biblioteket inte längre genererar en Order-ID för väntande köp. I dessa fall är orderId Den kommer bara att vara tillgänglig när köpet når statusen KÖPT. Detta påverkar särskilt arbetsflöden där du använde order-ID som primär referens från början.
Googles rekommendation är att du förlitar dig på purchaseToken för dina register och avstämningaråtminstone medan transaktionen väntar. Om du hittar ett köp som har försvunnit från Play, kontrollera Vad man ska göra om köpet försvinner.
Om du inte har arbetat med utestående saldon än, granska integrationsguiden och dokumentationen för faktureringsbiblioteket på hantering av upphandlingslivscykelnDär hittar du de olika tillstånden, hur du ska reagera på vart och ett och hur RTDN:er passar in i detta pussel.
Nya valfria funktioner i PBL 7: virtuella avbetalningar och förskottsbetalningar
Bland de "trevliga" nya funktionerna i PBL 7 finns virtuella avgiftsabonnemang (virtuella avbetalningsabonnemang) och utökat stöd för väntande köp för förbetalda abonnemang. Dessa funktioner är inte obligatoriska, men de kan ge dig mer flexibilitet när du anpassar din affärsmodell till olika marknader.
Virtuella avbetalningar gör det möjligt för en användare att betala för en längre prenumeration i små periodiska betalningarGoogle förklarar att du, i stället för en enda stor betalning, fortsätter att få månatliga betalningar för utvecklare enligt en årsplan med månatliga avbetalningar. Om en användare missar en betalning bör varken du eller Google försöka återkräva tidigare avbetalningar. Detta gör dess praktiska användning ganska lik en vanlig månadsprenumeration, åtminstone initialt.
För närvarande är dessa prenumerationsavgifter endast tillgängliga i Brasilien, Frankrike, Italien och SpanienGoogle rekommenderar att du håller utkik på Play Console för nya länder som stöds. Konfigurationen görs via ProductDetails.InstallmentPlanDetails och följ den specifika guiden för att integrera dem i din app.
Parallellt utökas stödet väntande köp för förbetalda prenumerationerNu kan ni erbjuda modeller där användaren startar köpet i appen och slutför betalningen senare via andra metoder, och faktureringsbiblioteket vet hur det ska hanteras korrekt. Aktivering sker genom att anropa enablePendingPurchases() vid initialisering av BillingClient och, specifikt för förbetalda planer, med hjälp av PendingPurchasesParams.Builder.enablePrepaidPlans().
Avskrivningsperioder för Play Billing Library 5 och 6
Med PBL 7 på gång har Google satt tydliga datum för tillbakadragande av stöd för version 5 och 6Om du fortfarande befinner dig i någon av dem måste du markera kalendern med rött:
- Google Play Billing Library 5 kommer officiellt att fasas ut den 31 augusti 2024 för nya appar och uppdateringar. Det är möjligt att begära en förlängning till den 1 november 2024, men det är inte något du bör förlita dig på i längden.
- Google Play Billing Library 6 kan användas för att publicera nya appar fram till den 1 augusti 2025 och för att uppdatera befintliga appar fram till den 1 november 2025.
Efter det datumet, om du inte har migrerat till åtminstone version 6 eller helst till version 7, måste du uppdatera till den senaste versionen. version 7Uppdateringar kommer att blockeras i Play Console. Även om din app fortsätter att fungera på användarnas enheter kommer den att frysas och inte kunna åtgärda buggar eller lägga till nya funktioner som är beroende av publicering i butiken.
Fallet med .NET MAUI och nuvarande begränsningar
Om du arbetar med .NET MAUI och prenumerationer på Android har du förmodligen redan läst eller upplevt att det inte är så enkelt. Många projekt använde Plugin.InAppBilling av James Montemagno, men plugin-programmet är arkiverat och underhålls inte, så det kommer inte att uppdateras för att stödja Billing Library 7. Samtidigt, det officiella paketet Xamarin.Android.Google.BillingClient Den har förblivit förankrad i Xamarin.Android-ekosystemet och är inte direkt kompatibel med .NET MAUI.
Den praktiska konsekvensen är att Play Console varnar Din app använder inte Billing Library 7.0.0 eller senare, vilket blockerar uppdateringar om du fortsätter att använda äldre bibliotek. Vissa utvecklare har valt drastiska lösningar, som att tillfälligt inaktivera prenumerationer för att kunna ladda upp en version, men det är uppenbarligen inte hållbart om din affärsmodell är beroende av den intäktsgenereringen.
I detta sammanhang överväger många lag alternativ som t.ex. SDK:er från tredje part Dessa tjänster stöder redan PBL 7 nedan och erbjuder ett mer stabilt, plattformsoberoende API (till exempel prenumerationsbackend-lösningar med SDK:er för Android, iOS och andra plattformar). Dessa tjänster hanterar vanligtvis versionsmigreringar av Billing Library och erbjuder ett stabilt omslag, vilket avsevärt minskar stressen med varje ny Google-utfasning.
Tills Microsoft och MAUI-teamet erbjuder en Officiellt paket uppdaterat och helt kompatibelt Med Billing Library 7 finns alternativen: att implementera din egen koppling till det inbyggda Billing Library, använda en tredjepartstjänst eller tänka om hur du integrerar köp i ditt MAUI-projekt. I vilket fall som helst är det bäst att inte vänta med beslutet till sista minuten, eftersom Plays deadlines är fasta.
Sammantaget innebär uppdateringen av Google Play Billing Library v7 att granska beroenden, rensa bort föråldrade API:er, stärka backend-logiken med köpverifiering och RTDN, och utnyttja testverktyg som Play Billing Lab för att upptäcka alla buggar innan de lanseras. De som tar sig tid att finjustera denna migrering kommer bättre att kunna hantera förbetalda abonnemang, virtuella avgifter, nätverksfel och förändringar i prenumerationslivscykeln, och kommer att ha en mycket bättre chans att upprätthålla stabila intäkter och en polerad användarupplevelse på Google Play. Dela informationen så att fler användare kan lära sig om ämnet.