Delen via

Wijzigingen in StoreKit in iOS 6

  • Artikel

iOS 6 heeft twee wijzigingen geïntroduceerd in de Store Kit-API: de mogelijkheid om iTunes-producten (en App Store/iBookstore) weer te geven vanuit uw app en een nieuwe in-app aankoopoptie waar Apple uw downloadbare bestanden host. In dit document wordt uitgelegd hoe u deze functies implementeert met Xamarin.iOS.

De belangrijkste wijzigingen in Store Kit in iOS6 zijn deze twee nieuwe functies:

  • In-App Content Display & Aankoop: gebruikers kunnen apps, muziek, boeken en andere iTunes-inhoud kopen en downloaden zonder uw app te verlaten. U kunt ook een koppeling maken naar uw eigen apps om het stimuleren van aankopen of beoordelingen en waarderingen aan te moedigen.
  • In-App Hosted Content aanschaffen: Apple slaat de inhoud op die is gekoppeld aan uw in-app-aankoopproducten, waardoor er geen afzonderlijke server meer nodig is om uw bestanden te hosten, wordt het downloaden op de achtergrond automatisch ondersteund en kunt u minder code schrijven.

Raadpleeg de handleidingen In-App Purchase voor gedetailleerde dekking van de StoreKit-API's.

Eisen

De Functies van de Store Kit die in dit document worden besproken, vereisen iOS 6 en Xcode 4.5, samen met Xamarin.iOS 6.0.

In-App inhoud weergeven & kopen

Met de nieuwe in-app-aankoopfunctie in iOS kunnen gebruikers productgegevens bekijken en het product kopen of downloaden vanuit uw app. Voorheen moesten toepassingen iTunes, de App Store of de iBookstore activeren, waardoor de gebruiker de oorspronkelijke toepassing verlaat. Deze nieuwe functie retourneert de gebruiker automatisch naar uw app wanneer deze klaar is.

Automatisch terugkeren naar een app na aankoop

Voorbeelden van hoe dit kan worden gebruikt, zijn:

  • Gebruikers aanmoedigen om uw app te beoordelen: u kunt de App Store-pagina openen, zodat de gebruiker uw app kan beoordelen en beoordelen zonder deze te verlaten.
  • Kruispromotie van apps – Hiermee kunt u gebruikers laten zien welke andere apps u publiceert, met de mogelijkheid om deze direct te kopen/downloaden.
  • Gebruikers helpen bij het vinden en downloaden van inhoud : help gebruikers om inhoud te kopen die door uw app wordt gevonden, beheerd of samengevoegd (bijvoorbeeld een muziekgerelateerde app kan een afspeellijst met nummers bieden en toestaan dat elk nummer in de app kan worden gekocht).

Zodra de SKStoreProductViewController is weergegeven, kan de gebruiker communiceren met de productgegevens alsof deze zich in iTunes, de App Store of de iBookstore bevinden. De gebruiker kan:

  • Schermopnamen weergeven (voor apps),
  • Voorbeeldnummers of video 's (voor muziek, tv-programma's en films),
  • Beoordelingen lezen (en schrijven),
  • Koop de &-download, die volledig plaatsvindt binnen de weergavecontroller en de Store Kit.

Sommige opties in de SKStoreProductViewController dwingen de gebruiker nog steeds uw app te verlaten en de relevante Store-app te openen, zoals klikken op verwante producten of de koppeling Ondersteuning voor van een app.

SKStoreProductViewController

De API voor het weergeven van een product in een app is eenvoudig: hiervoor hoeft u alleen een SKStoreProductViewControllerte maken en weer te geven. Volg deze stappen om een product te maken en weer te geven:

  1. Maak een StoreProductParameters-object om parameters door te geven aan de weergavecontroller, inclusief de productId in de constructor.
  2. Instantieer de SKProductViewController. Wijs het toe aan een veld op klasseniveau.
  3. Wijs een handler toe aan de gebeurtenis Finished van de weergavecontroller, waardoor de weergavecontroller moet worden gesloten. Deze gebeurtenis wordt aangeroepen wanneer de gebruiker op Annuleren drukt; of voltooit een transactie in de weergavecontroller.
  4. Roep de LoadProduct-methode aan, waarbij je de StoreProductParameters en een voltooiingshandler doorgeeft. De voltooiingshandler moet controleren of de productaanvraag succesvol was, en als dat zo is, de SKProductViewController modaal presenteren. De juiste foutafhandeling moet worden toegevoegd voor het geval het product niet kan worden opgehaald.

Voorbeeld

Het ProductView-project in de voorbeeldcode StoreKit voor dit artikel implementeert een Buy methode die de Apple ID van een product accepteert en de SKStoreProductViewControllerweergeeft. In de volgende code wordt de productinformatie voor een bepaalde Apple-id weergegeven:

void Buy (int productId)
{
    var spp = new StoreProductParameters(productId);
    var productViewController = new SKStoreProductViewController ();
    // must set the Finished handler before displaying the view controller
    productViewController.Finished += (sender, err) => {
        // Apple's docs says to use this method to close the view controller
        this.DismissModalViewControllerAnimated (true);
    };
    productViewController.LoadProduct (spp, (ok, err) => { // ASYNC !!!
        if (ok) {
            PresentModalViewController (productViewController, true);
        } else {
            Console.WriteLine (" failed ");
            if (err != null)
                Console.WriteLine (" with error " + err);
        }
    });
}

De app ziet er als volgt uit wanneer deze wordt uitgevoerd: downloaden of kopen vindt volledig plaats in de SKStoreProductViewController:

De app ziet er als volgt uit wanneer wordt uitgevoerd

Oudere besturingssystemen ondersteunen

De voorbeeldtoepassing bevat code die laat zien hoe u de App Store, iTunes of iBookstore opent in eerdere versies van iOS. Gebruik de methode OpenUrl om een correct gemaakte itunes.com-URL te openen.

U kunt een versiecontrole implementeren om te bepalen welke code moet worden uitgevoerd, zoals hier wordt weergegeven:

if (UIDevice.CurrentDevice.CheckSystemVersion (6,0)) {
    // do iOS6+ stuff, using SKStoreProductViewController as shown above
} else {
    // don't do stuff requiring iOS 6.0, use the old syntax
    // (which will take the user out of your app)
    var nsurl = new NSUrl("http://itunes.apple.com/us/app/angry-birds/id343200656?mt=8");
    UIApplication.SharedApplication.OpenUrl (nsurl);
}

Fouten

De volgende fout treedt op als de Apple-id die u gebruikt, niet geldig is, wat verwarrend kan zijn, omdat dit een netwerk- of verificatieprobleem van een bepaalde soort impliceert.

Error Domain=SKErrorDomain Code=5 "Cannot connect to iTunes Store"

Documentatie voor Objective-C lezen

Ontwikkelaars die lezen over Store Kit in de ontwikkelaarsportal van Apple, zien een protocol ( SKStoreProductViewControllerDelegate ) die met betrekking tot deze nieuwe functie zijn besproken. Het delegate-protocol heeft slechts één methode: productViewControllerDidFinish, die is weergegeven als de Finished gebeurtenis op de SKStoreProductViewController in Xamarin.iOS.

Apple ID's identificeren

De Apple ID die door de SKStoreProductViewController is vereist, is een nummer (niet te verwarren met bundel-id's zoals 'com.xamarin.mwc2012'). Er zijn een aantal verschillende manieren waarop u de Apple ID kunt vinden voor producten die u wilt weergeven, zoals hieronder wordt vermeld:

iTunesConnect

Voor toepassingen die u publiceert, kunt u eenvoudig de Apple ID vinden in iTunes Connect:

De Apple-id zoeken in iTunes Connect

Zoek-API

Apple biedt een dynamische zoek-API om een query uit te voeren op alle producten in de App Store, iTunes en de iBookstore. Informatie over hoe u toegang krijgt tot de zoek-API vindt u in de partnerbronnen van Apple, hoewel de API beschikbaar is voor iedereen (niet alleen geregistreerde partners). De resulterende JSON kan worden geparseerd om de trackId te ontdekken die de Apple-id is die moet worden gebruikt met SKStoreProductViewController.

De resultaten bevatten ook andere metagegevens, waaronder weergave-informatie en url's voor illustraties die kunnen worden gebruikt om het product in uw app weer te geven.

Hier volgen enkele voorbeelden:

Partnerinformatie voor ondernemingen

Apple biedt goedgekeurde partners een volledige gegevensdump van al hun producten, in de vorm van downloadbare, platte bestanden die gereed zijn voor databases. Als u in aanmerking komt voor toegang tot de Enterprise Partner Feed, vindt u de Apple ID voor elk product in die gegevensset.

Veel gebruikers van de Enterprise Partner Feed zijn lid van het Affiliate Program waarmee commissies kunnen worden verdiend op productverkoop. SKStoreProductViewController ondersteunt geen affiliate-id's (op het moment van schrijven).

De Apple ID voor een product kan worden afgeleid van de URL-koppeling voor iTunes Preview. Zoek in alle iTunes-productkoppelingen (voor apps, muziek of boeken) het deel van de URL vanaf id en gebruik het nummer dat volgt.

De directe koppeling naar iBooks is bijvoorbeeld

http://itunes.apple.com/us/app/ibooks/id364709193?mt=8

en de Apple ID is 364709193. Hetzelfde geldt voor de MWC2012-app, de directe koppeling is

http://itunes.apple.com/us/app/mwc-2012-unofficial/id496963922?mt=8

en de Apple ID is 496963922.

gehoste inhoud kopen In-App

Als uw in-app-aankopen bestaan uit downloadbare inhoud (zoals boeken of andere media, game level art en configuratie of andere grote bestanden), worden deze bestanden vroeger gehost op uw webserver en moesten apps code opnemen om ze veilig te downloaden na aankoop. Vanaf iOS 6 host Apple uw bestanden op hun servers, zodat er geen afzonderlijke server meer nodig is. De functie is alleen beschikbaar voor niet-verbruiksproducten (niet verbruikbaar of abonnementen). Voordelen van het gebruik van de hostingservice van Apple zijn onder andere:

  • Bespaar hosting & bandbreedtekosten.
  • Waarschijnlijk beter schaalbaar dan welke serverhost u momenteel gebruikt.
  • Minder code om te schrijven, omdat u geen verwerking aan de serverzijde hoeft te bouwen.
  • Downloaden op de achtergrond wordt voor u geregeld.

Opmerking: het testen van gehoste in-app-aankoopinhoud in iOS Simulator wordt niet ondersteund, dus u moet testen met een echt apparaat.

Basisbeginselen van gehoste inhoud

Vóór iOS 6 waren er twee manieren om een product te leveren (beschreven in Xamarin-documentatie In-App Purchase):

  • Built-In Producten : functies die 'ontgrendeld' zijn door aankoop, maar die zijn ingebouwd in de toepassing (als code of ingesloten resources). Voorbeelden van ingebouwde producten zijn ontgrendelde fotofilters of in-game power-ups.
  • Server-Delivered Producten – Na aankoop moet de toepassing inhoud downloaden van een server die u gebruikt. Deze inhoud wordt gedownload tijdens de aankoop, opgeslagen op het apparaat en vervolgens weergegeven als onderdeel van het leveren van het product. Voorbeelden hiervan zijn boeken, tijdschriftnummers of spelniveaus die bestaan uit achtergrondillustraties en configuratiebestanden.

In iOS 6 biedt Apple een variatie op door de server geleverde producten: ze hosten uw inhoudsbestanden op hun servers. Dit maakt het veel eenvoudiger om door de server geleverde producten te bouwen, omdat u geen afzonderlijke server hoeft te gebruiken en Store Kit biedt functionaliteit voor het downloaden van achtergronden die u eerder zelf moest schrijven. Als u wilt profiteren van de hosting van Apple, schakelt u contenthosting in voor nieuwe in-app-aankoopproducten en wijzigt u uw Store Kit-code om hiervan te profiteren. Productinhoudsbestanden worden vervolgens gebouwd met behulp van Xcode en geüpload naar de servers van Apple voor beoordeling en release.

Het proces bouwen en leveren

Voor het gebruik van de App Store voor het in-app aanschaffen van met gehoste inhoud is de volgende installatie en configuratie vereist:

  • iTunes Connect – U moet uw bank- en belastinggegevens aan Apple hebben verstrekt, zodat ze namens u geld kunnen terugvertalen. Vervolgens kunt u producten configureren om te verkopen en sandbox-gebruikersaccounts instellen om de aankoop te testen. U moet ook Gehoste inhoud configureren voor die niet-verbruiksproducten die u wilt hosten met Apple.
  • iOS-voorzieningsportal: een bundelidentificatie maken en App Store-toegang voor uw app inschakelen, zoals u zou doen voor elke toepassing die in-app aankopen ondersteunt.
  • Store Kit: code toevoegen aan uw app voor het weergeven van producten, aankoopproducten en het herstellen van transacties. In iOS 6 Store Kit beheert u ook het downloaden van uw productinhoud, op de achtergrond, met voortgangsupdates.
  • aangepaste code: om aankopen van klanten bij te houden en de producten of services te leveren die ze hebben gekocht. Gebruik nieuwe iOS 6 Store Kit-klassen zoals SKDownload om de inhoud op te halen die wordt gehost door Apple.

In de volgende secties wordt uitgelegd hoe u gehoste inhoud implementeert, van het maken en uploaden van het pakket tot het beheren van het aankoop- en downloadproces, met behulp van de voorbeeldcode voor dit artikel.

Voorbeeldcode

In het voorbeeldproject HostedNonConsumables (in StoreKitiOS6.zip) wordt gehoste inhoud gebruikt. De app biedt twee 'boekhoofdstukken' te koop aan, waarvan de inhoud gehost wordt op de servers van Apple. De inhoud bestaat uit een tekstbestand en een afbeelding, hoewel veel complexere inhoud kan worden gebruikt in een echte toepassing.

De app ziet er als volgt uit vóór, tijdens en na een aankoop:

De app ziet er als volgt uit: vóór, tijdens en na een aankoop

Het tekstbestand en de afbeelding worden gedownload en gekopieerd naar de map Documenten van de toepassing. Zie de documentatie van het bestandssysteemvoor meer informatie over de verschillende mappen die beschikbaar zijn voor toepassingsopslag.

iTunes Connect

Wanneer u nieuwe producten maakt die gebruikmaken van de hosting van Apple-inhoud, moet u ervoor zorgen dat u de niet-verbruiksbare producttype selecteert. Andere producttypen bieden geen ondersteuning voor het hosten van inhoud. Bovendien moet u het hosten van inhoud niet inschakelen voor bestaande producten die u verkoopt; schakel alleen hosting van inhoud in voor nieuwe producten.

Selecteer het producttype Niet-verbruiksproduct

Voer een product-ID in. Deze id is later vereist wanneer u de inhoud voor dit product maakt.

een product-id invoeren

Hosting van inhoud wordt ingesteld in de sectie Details. Voordat de in-app-aankoop live gaat, schakelt u het selectievakje Host Content bij Apple uit als u wilt annuleren (zelfs als u wat testinhoud hebt geüpload). Het hosten van inhoud kan echter niet worden verwijderd nadat de aankoop in de app live is gegaan.

Inhoud hosten met Apple

Zodra u hostinginhoud hebt ingeschakeld, zal het product de status Wacht op uploaden aannemen en dit bericht weergeven:

Het product wacht op uploadstatus en geeft dit bericht weer

Het inhoudspakket moet worden gemaakt met Xcode en geüpload met behulp van het hulpprogramma Archief. Instructies voor het maken van inhoudspakketten zijn te vinden in de volgende sectie Maken .PKG Files.

Maken van .PKG-bestanden

De inhoudsbestanden die u uploadt naar Apple, moeten voldoen aan de volgende beperkingen:

  • Kan niet groter zijn dan 2 GB.
  • Kan geen uitvoerbare code (of symlinks die buiten de inhoud verwijzen) bevatten.
  • Moet correct zijn opgemaakt (inclusief een .plist-bestand) en een .pkg bestandsextensie hebben. Dit wordt automatisch gedaan als u deze instructies volgt met behulp van Xcode.

U kunt veel verschillende bestanden en typen bestanden toevoegen, zolang ze aan deze beperkingen voldoen. nl-NL: De inhoud wordt gecomprimeerd voordat deze naar uw applicatie wordt geleverd en uitgepakt door Store Kit voordat uw code er toegang toe krijgt.

Na het uploaden van een inhoudspakket kan het worden vervangen door nieuwere inhoud. Nieuwe inhoud moet worden geüpload en ingediend voor beoordeling/goedkeuring via het normale proces. Verhoog het ContentVersion veld in bijgewerkte inhoudspakketten om aan te geven dat het nieuwer is.

Xcode In-App Content-projecten aanschaffen

Voor het maken van pakketten met inhoud voor in-app-aankoopproducten is momenteel Xcode vereist. Er is GEEN OBJECTIVE-C CODERING vereist; Xcode heeft een nieuw projecttype voor deze pakketten die alleen uw bestanden en een plist bevatten.

In onze voorbeeldtoepassing zijn boekhoofdstukken te koop: elk hoofdstukinhoudspakket bevat:

  • een tekstbestand en
  • een afbeelding die het hoofdstuk vertegenwoordigt.

Selecteer eerst Bestand > Nieuw project in het menu en kies In-App Inhoud kopen:

Kies In-App Inhoud kopen

Voer de productnaam en bedrijfs-id in zodat de bundel-id overeenkomt met de product-id die u hebt ingevoerd in iTunes Connect voor dit product.

voer de naam en id in

U hebt nu een leeg project In-App Aankoopinhoud. U kunt met de rechtermuisknop klikken en bestanden toevoegen ... of sleep ze naar de Project Navigator-. Zorg ervoor dat de ContentVersion juist is (deze moet beginnen bij 1.0, maar als u er later voor kiest om uw inhoud bij te werken, moet u deze verhogen).

In deze schermopname ziet u Xcode met de inhoudsbestanden die zijn opgenomen in het project en de plist-vermeldingen die zichtbaar zijn in het hoofdvenster:

Deze schermopname toont Xcode met de inhoudsbestanden die zijn opgenomen in het project en de plist-vermeldingen die zichtbaar zijn in het hoofdvenster

Nadat u al uw inhoudsbestanden hebt toegevoegd, kunt u dit project opslaan en later opnieuw bewerken of het uploadproces starten.

Uploaden van .PKG-bestanden

De eenvoudigste manier om inhoudspakketten te uploaden is met het Xcode Archive Tool. Kies Product > Archive in het menu om te beginnen:

Archiven- kiezen

Het inhoudspakket wordt vervolgens weergegeven in het archief, zoals hieronder wordt weergegeven. Het archieftype en -pictogram tonen dat deze regel een In-App Aankoopinhoudarchiefis. Klik op Valideren... om ons inhoudspakket te controleren op fouten zonder de upload daadwerkelijk uit te voeren.

het pakket valideren

Meld u aan met uw iTunes Connect-referenties:

meld u aan met uw iTunes Connect-referenties

Kies de juiste toepassing en in-app-aankoop om deze inhoud te koppelen aan:

De juiste toepassing en in-app-aankoop kiezen om deze inhoud te koppelen aan

U zou een bericht moeten zien zoals in deze schermafbeelding.

Een voorbeeld van een bericht zonder problemen

Voer nu een vergelijkbaar proces uit, maar als je op Distribueren... klikt, wordt de inhoud daadwerkelijk geüpload.

De app distribueren

Selecteer de eerste optie om de inhoud te uploaden:

De inhoud uploaden

Meld u opnieuw aan:

aanmelden bij

Kies de juiste toepassings- en aankooprecord in de app om de inhoud te uploaden naar:

Kies de toepassing en de aankooprecord in de app

Wacht tot uw bestanden zijn geüpload:

Het dialoogvenster Voor het uploaden van inhoud

Wanneer het uploaden is voltooid, wordt er een bericht weergegeven waarin wordt aangegeven dat de inhoud is verzonden naar de App Store.

een voorbeeld van een geslaagd uploadbericht

Wanneer u teruggaat naar de productpagina op iTunes Connect, worden de pakketgegevens weergegeven en bevindt u zich in Gereed om status in te dienen. Wanneer het product deze status heeft, kunt u beginnen met testen in de sandbox-omgeving. U hoeft het product niet te 'verzenden' voor tests in de sandbox.

iTunes Connect zullen de pakketgegevens weergegeven worden en de status in Gereed voor verzenden zijn

Het kan enige tijd duren (bijvoorbeeld een paar minuten) tussen het uploaden van het archief en de iTunes Connect-status die wordt bijgewerkt. U kunt het product afzonderlijk indienen voor beoordeling of het indienen in combinatie met een binair bestand van een toepassing. Pas nadat Apple officieel de inhoud heeft goedgekeurd, is deze beschikbaar in de productie-App Store voor aankoop in uw app.

PKG-bestandsindeling

Als u Xcode en het archiefprogramma gebruikt om een gehost inhoudspakket te maken en te uploaden, ziet u nooit de inhoud van het pakket zelf. De bestanden en mappen in de pakketten die voor de voorbeeld-app zijn gemaakt, zien er als volgt uit, met het plist--bestand in de hoofdmap en de productbestanden in een Inhoud submap:

Het plist-bestand in de hoofdmap en de productbestanden in een Contents-submap

Let op de mapstructuur van het pakket (met name de locatie van de bestanden in de submap Contents) omdat u deze informatie moet begrijpen om de bestanden uit het pakket op het apparaat te extraheren.

Pakketinhoud bijwerken

De procedure voor het bijwerken van inhoud nadat deze is goedgekeurd:

  • Bewerk het project In-App Purchase Content in Xcode.
  • Het versienummer verhogen.
  • Upload opnieuw naar iTunes Connect. Volgende kopers krijgen automatisch de nieuwste versie, MAAR gebruikers die al de oude versie hebben, ontvangen geen melding.
  • Uw app is verantwoordelijk voor het melden van gebruikers en het aanmoedigen van gebruikers om een nieuwere versie van de inhoud op te halen. De app moet ook een functie bouwen waarmee de nieuwe versie wordt gedownload met behulp van de functie Herstellen van Store Kit.
  • Als u wilt bepalen of er een nieuwere versie bestaat, kunt u een functie in uw app bouwen om SKProducts op te halen (bijvoorbeeld hetzelfde proces dat wordt gebruikt om productprijzen op te halen) en de eigenschap ContentVersion te vergelijken.

Aankoopoverzicht

Voordat u deze sectie leest, raadpleegt u de bestaande documentatie In-App Aankoopdocumentatie.

De volgorde van gebeurtenissen die optreden wanneer een product met gehoste inhoud wordt gekocht en gedownload, wordt geïllustreerd in dit diagram:

De volgorde van gebeurtenissen die optreden wanneer een product met gehoste inhoud wordt gekocht en downloaden

  1. Nieuwe producten kunnen worden gemaakt in iTunes Connect met gehoste inhoud ingeschakeld. De werkelijke inhoud wordt afzonderlijk samengesteld in Xcode (net als het slepen van bestanden naar een map) en vervolgens gearchiveerd en geüpload naar iTunes (er is geen codering vereist). Elk product wordt vervolgens ter goedkeuring ingediend, waarna het beschikbaar is voor aankoop. In de voorbeeldcode zijn deze product-id's vastgelegd, maar het hosten van inhoud met Apple is flexibeler als u de beschikbare productlijst op een externe server opslaat, zodat deze kan worden bijgewerkt wanneer u nieuwe producten en inhoud verzendt naar iTunes Connect.
  2. Wanneer de gebruiker een product koopt, wordt een transactie in de betalingswachtrij geplaatst voor verwerking.
  3. Store Kit stuurt de aankoopaanvraag door naar iTunes-servers voor verwerking.
  4. Transactie wordt voltooid op de iTunes-servers (bijvoorbeeld klant wordt in rekening gebracht) en er wordt een ontvangstbewijs geretourneerd naar de app, waarbij productinformatie is bijgevoegd, inclusief of het kan worden gedownload (en zo ja, de bestandsgrootte en andere metagegevens).
  5. Uw code moet controleren of het product kan worden gedownload en als dat het geval is, moet u een aanvraag indienen voor het downloaden van inhoud die ook in de betalingswachtrij wordt geplaatst. Store Kit verzendt deze aanvraag naar de iTunes-servers.
  6. Server retourneert het inhoudsbestand naar Store Kit, dat een callback biedt om de voortgang van het downloaden en de resterende tijdschattingen naar uw code te retourneren.
  7. Zodra dit is voltooid, ontvangt u een melding en ontvangt u een bestandslocatie in de Cache-map.
  8. Uw code moet de bestanden kopiëren en verifiëren en de benodigde gegevens opslaan om te onthouden dat het product is aangekocht. Neem deze kans om de back-upvlag correct in te stellen op de nieuwe bestanden (hint: als ze afkomstig zijn van een server en nooit door de gebruiker worden bewerkt, moet u waarschijnlijk back-ups overslaan, omdat de gebruiker deze altijd kan ophalen van apple-servers in de toekomst).
  9. Roep FinishTransaction aan. Deze stap is BELANGRIJK omdat de transactie uit de betalingswachtrij wordt verwijderd. Het is ook belangrijk dat u FinishTransaction pas aanroept nadat u de inhoud uit de cachemap hebt gekopieerd. Zodra u FinishTransaction aanroept, worden de bestanden in de cache waarschijnlijk snel opgeschoond.

Implementeren van Hosted Content Purchase

De volgende informatie moet in samenhang worden gelezen met de volledige documentatie van de aankopen In-App. De informatie in dit document is gericht op de verschillen tussen gehoste inhoud en de vorige implementatie.

Klassen

De volgende klassen zijn toegevoegd of gewijzigd ter ondersteuning van gehoste inhoud in iOS 6:

  • SKDownload : nieuwe klasse die een download vertegenwoordigt die wordt uitgevoerd. De API staat meer dan één product toe, maar in eerste instantie is er slechts één geïmplementeerd.
  • SKProduct: nieuwe eigenschappen toegevoegd: Downloadable, ContentVersion, ContentLengths array.
  • SKPaymentTransaction – Nieuwe eigenschap toegevoegd: Downloads, die een verzameling SKDownload objecten bevat als dit product inhoud bevat die kan worden gedownload.
  • SKPaymentQueue – Nieuwe methode toegevoegd: StartDownloads. Roep deze methode aan met SKDownload objecten om hun gehoste inhoud op te halen. Downloaden kan op de achtergrond plaatsvinden.
  • SKPaymentTransactionObserver – Nieuwe methode: UpdateDownloads. Store Kit roept deze methode aan met voortgangsinformatie over de huidige downloadbewerkingen.

Details van de nieuwe SKDownload-klasse:

  • voortgangs-: een waarde tussen 0 en 1 die u kunt gebruiken om een indicator voor het percentage voltooid voor de gebruiker weer te geven. Gebruik GEEN voortgang == 1 om te detecteren of het downloaden is voltooid. Controleer op Status == Voltooid.
  • TimeRemaining- : schatting van de resterende downloadtijd in seconden. -1 betekent dat de schatting nog steeds wordt berekend.
  • status: actief, wachten, voltooid, mislukt, onderbroken, geannuleerd.
  • ContentURL : bestandslocatie waar de inhoud op schijf is geplaatst, in de map Cache. Alleen ingevuld zodra het downloaden is voltooid.
  • Fout: controleer deze eigenschap als de status op 'Mislukt' staat.

De interacties tussen de klassen in de voorbeeldcode worden weergegeven in dit diagram (de code die specifiek is voor gehoste inhoudsaankopen wordt groen weergegeven):

Aankopen van gehoste inhoud worden groen weergegeven in dit diagram

De voorbeeldcode waarin deze klassen zijn gebruikt, wordt weergegeven in de rest van deze sectie:

CustomPaymentObserver (SKPaymentTransactionObserver)

Wijzig de bestaande UpdatedTransactions-overschrijving om te controleren op downloadbare inhoud en roep StartDownloads aan indien nodig.

public override void UpdatedTransactions (SKPaymentQueue queue, SKPaymentTransaction[] transactions)
{
    foreach (SKPaymentTransaction transaction in transactions) {
        switch (transaction.TransactionState) {
        case SKPaymentTransactionState.Purchased:
            // UPDATED FOR iOS 6
            if (transaction.Downloads != null && transaction.Downloads.Length > 0) {
                // Purchase complete, and it has downloads... so download them!
                SKPaymentQueue.DefaultQueue.StartDownloads (transaction.Downloads);
                // CompleteTransaction() call has moved after downloads complete
            } else {
                // complete the transaction now
                theManager.CompleteTransaction(transaction);
            }
            break;
        case SKPaymentTransactionState.Failed:
            theManager.FailedTransaction(transaction);
            break;
        case SKPaymentTransactionState.Restored:
            // TODO: you must decide how to handle restored transactions.
            // Triggering all the downloads at once is not advisable.
            theManager.RestoreTransaction(transaction);
            break;
        default:
            break;
        }
    }
}

De nieuwe overschreven methode UpdatedDownloads wordt hieronder weergegeven. Store Kit roept deze methode aan nadat StartDownloads is geactiveerd in UpdatedTransactions. Deze methode wordt meerdere keren met onbepaalde intervallen aangeroepen om u de voortgang van het downloaden te bieden en vervolgens opnieuw wanneer het downloaden is voltooid. U ziet dat de methode een matrix van SKDownload objecten accepteert, zodat elke methodeaanroep u de status van meerdere downloads in de wachtrij kan bieden. Zoals in de implementatie hieronder wordt weergegeven, worden de downloadstatussen elke keer gecontroleerd en de juiste actie ondernomen.

// ENTIRELY NEW METHOD IN iOS6
public override void PaymentQueueUpdatedDownloads (SKPaymentQueue queue, SKDownload[] downloads)
{
    Console.WriteLine (" -- PaymentQueueUpdatedDownloads");
    foreach (SKDownload download in downloads) {
        switch (download.DownloadState) {
        case SKDownloadState.Active:
            // TODO: implement a notification to the UI (progress bar or something?)
            Console.WriteLine ("Download progress:" + download.Progress);
            Console.WriteLine ("Time remaining:   " + download.TimeRemaining); // -1 means 'still calculating'
            break;
        case SKDownloadState.Finished:
            Console.WriteLine ("Finished!!!!");
            Console.WriteLine ("Content URL:" + download.ContentUrl);

            // UNPACK HERE! Calls FinishTransaction when it's done
            theManager.SaveDownload (download);

            break;
        case SKDownloadState.Failed:
            Console.WriteLine ("Failed"); // TODO: UI?
            break;
        case SKDownloadState.Cancelled:
            Console.WriteLine ("Canceled"); // TODO: UI?
            break;
        case SKDownloadState.Paused:
        case SKDownloadState.Waiting:
            break;
        default:
            break;
        }
    }
}

InAppPurchaseManager (SKProductsRequestDelegate)

Deze klasse bevat een nieuwe methode SaveDownload die wordt aangeroepen nadat elke download is voltooid.

De gehoste inhoud is succesvol gedownload en uitgepakt in de map Cache. De structuur van de . PKG-bestand vereist dat alle bestanden worden opgeslagen in een Contents submap, dus met de onderstaande code worden bestanden uit de Contents submap geëxtraheerd.

De code doorloopt alle bestanden in het inhoudspakket en kopieert deze naar de Documents map, in een submap met de naam van de ProductIdentifier. Ten slotte wordt CompleteTransactionaangeroepen, waarmee FinishTransaction wordt aangeroepen om de transactie uit de betalingswachtrij te verwijderen.

// ENTIRELY NEW METHOD IN iOS 6
public void SaveDownload (SKDownload download)
{
    var documentsPath = Environment.GetFolderPath (Environment.SpecialFolder.Personal); // Documents folder
    var targetfolder = System.IO.Path.Combine (documentsPath, download.Transaction.Payment.ProductIdentifier);
    // targetfolder will be "/Documents/com.xamarin.storekitdoc.montouchimages/" or something like that
    if (!System.IO.Directory.Exists (targetfolder))
        System.IO.Directory.CreateDirectory (targetfolder);
    foreach (var file in System.IO.Directory.EnumerateFiles
             (System.IO.Path.Combine(download.ContentUrl.Path, "Contents"))) { // Contents directory is the default in .PKG files
        var fileName = file.Substring (file.LastIndexOf ("/") + 1);
        var newFilePath = System.IO.Path.Combine(targetfolder, fileName);
        if (!System.IO.File.Exists(newFilePath)) // HACK: this won't support new versions...
            System.IO.File.Copy (file, newFilePath);
        else
            Console.WriteLine ("already exists " + newFilePath);
    }
    CompleteTransaction (download.Transaction); // so it gets 'finished'
}

Wanneer FinishTransaction wordt aangeroepen, is het niet langer gegarandeerd dat de gedownloade bestanden in de Cache directory zijn. Alle bestanden moeten worden gekopieerd voordat u FinishTransactionaanroept.

Andere overwegingen

In de bovenstaande voorbeeldcode ziet u een vrij eenvoudige implementatie van de aankoop van gehoste inhoud. Er zijn enkele aanvullende punten waarmee u rekening moet houden:

Bijgewerkte inhoud detecteren

Hoewel het mogelijk is om uw gehoste inhoudspakketten bij te werken, biedt Store Kit geen mechanisme om deze updates te pushen naar gebruikers die het product al hebben gedownload en gekocht. Om deze functionaliteit te implementeren, kan uw code regelmatig de nieuwe SKProduct.ContentVersion-eigenschap controleren (als de SKProductDownloadableis) en detecteren of de waarde wordt verhoogd. U kunt ook een pushmeldingssysteem bouwen.

Bijgewerkte inhoudsversies installeren

Met de bovenstaande voorbeeldcode wordt het kopiëren van bestanden overgeslagen als het bestand al bestaat. Dit is GEEN goed idee als u nieuwere versies van de inhoud wilt ondersteunen die worden gedownload.

Een alternatief is om de inhoud te kopiëren naar een map met de naam van de versie en om bij te houden welke versie de huidige versie is (bijvoorbeeld in NSUserDefaults of waar u de aankooprecords hebt opgeslagen).

Transacties herstellen

Wanneer SKPaymentQueue.DefaultQueue.RestoreCompletedTransactions wordt aangeroepen, retourneert Store Kit alle eerdere transacties voor de gebruiker. Als ze een groot aantal items hebben gekocht of als elke aankoop grote inhoudspakketten heeft, kan het herstel leiden tot veel netwerkverkeer omdat alles in de wachtrij wordt geplaatst voor downloaden in één keer.

Overweeg om bij te houden of een product afzonderlijk is gekocht bij de daadwerkelijke download van het bijbehorende inhoudspakket.

Downloads onderbreken, opnieuw opstarten en annuleren

Hoewel de voorbeeldcode deze functie niet demonstreert, is het mogelijk om gehoste inhoudsdownloads te onderbreken en opnieuw op te starten. De SKPaymentQueue.DefaultQueue heeft methoden voor PauseDownloads, ResumeDownloads en CancelDownloads.

Als de code FinishTransaction wordt aangeroepen in de betalingswachtrij voordat de download Finished is, wordt die download automatisch geannuleerd.

De SKIP-Backup-vlag instellen op de gedownloade inhoud

De iCloud-back-uprichtlijnen van Apple suggereren dat niet-gebruikersinhoud die eenvoudig van een server kan worden hersteld, geen back-up moet niet worden gemaakt (omdat deze onnodig iCloud-opslag zou gebruiken). Zie de documentatie voor het bestandssysteem voor meer informatie over het instellen van het back-upkenmerk.

Samenvatting

In dit artikel zijn twee nieuwe functies van De Store Kit in iOS6 geïntroduceerd: iTunes en andere inhoud kopen vanuit uw app en gebruikmaken van de server van Apple om uw eigen aankopen in de app te hosten. Deze inleiding moet worden gelezen in combinatie met de bestaande In-App Aankoopdocumentatie voor een volledig overzicht van de implementatie van de StoreKit-functionaliteit.