In app purchase Programming Guide (Chinese Version)

I. In app purchase Overview

Store kit represents the communication between the app and the App Store. The program will receive information about the products you want to provide from the App Store and display them for users to purchase.
When a user needs to buy a product, the program calls storekit to collect the purchase information. That is, the basic store kit model:

The store kit API is only a small part of the added in APP purchase function for the program. You need to decide how to record the products you want to submit and how to present the store functions to users in the program,
We also need to consider how to submit the products purchased by users. The rest of this chapter shows the entire process.

Products
A product can be any one of the features you want to sell. The product is organized in iTunes connect, which is the same as adding a new app. There are four types of products supported:
1. content type. This includes e-books, e-magazines, photos, illustrations, game levels, game roles, and other digital content.
2. Extended functions. These functions are included in the app. Locked before purchase. For example, you can include several games in a game program, and users can separately purchase these games.
3. Service. Allow programs to charge for a single service. For example, the recording service.
4. subscribe. Supports extended access to content or services. For example, your program can provide financial information or game portal information every week. A reasonable update cycle should be set to avoid frequent
This vulnerability affects users. Remember: you will be responsible for tracking subscription expiration information and managing subscriptions. App Store does not monitor subscription cycles for you, nor does it provide an automatic charging mechanism.

In app purchase provides a general mechanism for creating products and you are responsible for how to operate them. When designing a program, pay attention to the following points:

1. You must provide electronic products and services. Do not use in APP purchase to sell physical and actual services.
2. Goods that represent the intermediary currency cannot be provided, because it is important for users to know the goods and services they have purchased.

Register a product through App Store

Every product you want to sell must be registered in the app store through iTunes connect. You must provide the product name, description, price, and other metadata used in the program.

You must specify a unique identifier for the product. When your program uses the store kit to communicate with the App Store, it uses the product identifier to retrieve the product information. If a user purchases a product, the program can use this identifier to mark the product as "purchased ".

App Store simplifies the product categories mentioned earlier into the following three types:

1. consumable items. This type of product is bought only once when needed. For example, a single service.
2. non-consumable items. This product can be used only once by a user. Once purchased, devices associated with the user's iTunes account can use this product. Store kit provides built-in support for re-Storing non-consumable items on multiple devices.
3. Subscription class. Subscription products have the above two types of features. Like consumable items, subscription items can be purchased multiple times; you can add your own subscription plan update mechanism within the program. In addition, subscription products must be provided to all devices associated with a user. In app purchase expects that subscription products can be delivered through external servers. You must provide corresponding support for the subscription service for multiple devices.

For more information, see the iTunes connect developer guide.

Delivery Method

The delivery mechanism is of great significance in the design and implementation of the program in APP purchase. There are two basic models that can be used to deliver products: Built-in model and server model ). Regardless of the model, you need to maintain the product list and ensure that the product is successfully delivered after the user buys the product.

1. built-in product types
Use this model. The product to be delivered is already in the program. This method is usually used for some locked functions. It can also be used to deliver content in the app bundle. An important advantage of this method is that you can deliver products to customers in a timely manner. Most of the built-in products should be non-consumable products.

Note: In app purchase does not provide the patch purchase function. To change the app bundle, you must submit a new app version to the app store.

The identifier of the product to be stored in the bundle. In the built-in mode, Apple recommends using plist to record product identifiers. Content Applications can easily add new content without modifying the program itself. (The original saying is: Content-driven applications can use this to add new content without modifying the source for your application. I don't know much about it. I think it is similar to using plist to manage the product list, therefore, you do not need to change the program when adding a new product. Further discussion ...)

After the product is successfully purchased, the program should unlock the lock function and provide it to the user. The simplest way to unlock is to modify application preferences ). When a user backs up mobile phone data, the program preference settings are also backed up. It is recommended that you back up your mobile phone after purchasing the product to avoid losing the purchased content.

Figure 1-2 shows the process for delivering a built-in product.

1. The program obtains the list of product identifiers through the plist file stored in bundle.
2. The program sends a request to the App Store to obtain the product information.
3. app store returns product information.
4. The program displays the returned product information to the user (the store interface of the APP)
5. Select a product
6. The program sends a payment request to the app store.
7. The app store processes the payment request and returns the Transaction completion information.
8. The app obtains information and provides the content to users.

Picture: built-in.png

2. Server Type
To use this method, you must provide another server to send the product to the program. Server delivery applies to subscription, content-based products, and services, because goods can be sent as data without changing the program bundle. For example, a game provides new content (levels, etc ). Store kit does not define the design and interaction of the server. You need to complete this work. In addition, store kit does not provide a mechanism to authenticate user identities. You need to design it. If your program requires the above functions, such as recording the subscription plan of a specific user, you need to design and implement it by yourself.

Figure 1-3 shows the purchase process of the server type.

1. The program sends a request to the server to obtain a list of products.
2. The server returns a list containing product identifiers.
3. The program sends a request to the App Store to obtain the product information.
4. app store returns product information.
5. The program displays the returned product information to the user (the store interface of the APP)
6. Select a product
7. The program sends a payment request to the App Store
8. The app store processes the payment request and returns the Transaction completion information.
9. The program obtains data from the information and sends it to the server.
10. record data on the server and perform review (our.
11. The server sends data to the App Store to verify the validity of the transaction.
12. App Store parses the received data, returns the data, and indicates whether it is a valid identifier.
13. The server reads the returned data and determines the content purchased by the user.
14. The server passes the purchased content to the program.

Apple recommends that you store product IDs on the server rather than in plist. In this way, you can add a new product without upgrading the program.

In server mode, your program will obtain transaction-related information and send it to the server. The server can verify the received data and decode it to determine the content to be delivered. This process will be discussed in the "verify store receipt" section.

We have security and reliability concerns about the server model. You should test the entire environment to avoid threats. The secure coding guide document provides related instructions.

Although non-consumable items can be restored in Built-in mode, subscription items must be restored through servers. You are responsible for recording subscription information and restoring data.
Consumable products can also be recorded on servers. For example, if a server provides a service, you may need to obtain the result from multiple devices.
Obtain product information

To display the "Store" in the program, you need to obtain information from the app store to purchase the interface. This chapter describes how to obtain product information from the App Store.

Send a request to the App Store

Store kit provides a common mechanism to request data from the App Store. The program can create and initialize a request object, append the delegate object to it, and then start the request process. The request will be sent to the app store where it is processed. When the processing is complete, the request object's delegate method is called asynchronously to obtain the request results. Figure 2-1 shows the request data model.


If the program exits during the request, You Need To resend the request.

The following describes the classes used in the request process:

Skrequest
Skrequest is the abstract root class of the request.

Skrequestdelegate
Skrequestdelegate is a protocol used to process request results, such as request success or request failure.

Send a request to obtain Product Information
The program uses products request to obtain product information. To complete this process, the program needs to create a request object that contains a list of product IDs. As mentioned before, your program can be built into both a product list and an external server.

When a request is sent, the product ID is sent to the App Store, and the app store returns localized information (this information has been set in iTunes connect beforehand ), you will use this information to create a built-in store interface (display product name, description, and so on ). Figure 2-2 shows the request process.


Skproductsrequest
Used to request product information. When creating a product, we add the list of products to be displayed to this object.

SkproductsrequestdelegatE
This Protocol defines the method for processing the App Store response.

Skproductsresponse
The skproductsresponse object is the response information returned by the App Store. It contains two lists (nsarray of course): one is a verified product,
@ Property (nonatomic, readonly) nsarray * Products
The other is the unrecognized product information:
@ Property (nonatomic, readonly) nsarray * invalidproductidentifierS
There are several reasons that will make the product logo unidentifiable, such as spelling mistakes (of course) and marked as unavailable for sale ), or changes to product information are not sent to all App Store servers. (The reason is not clear. I will discuss it again ).

Skproduct
The skproduct object contains the localized information of the products registered on the app store.
Purchased items
When a user is preparing to purchase a product, the program requests the payment information from the App Store, and then the App Store creates persistent transaction information and continues to process the payment process, even if the user restarts the program, the same is true for this process. App Store synchronizes the list of pending transactions to the program, and sends updated data to the program when the transaction status changes.

Collect payment information

To collect payment information, your program can create a payment object and put it in the payment queue, as shown in 3-1.


1. A skpayment object contains the product ID of "sword", and the purchase quantity is set to 1.
2. Use addpayment: add the skpayment object to skpaymentqueue.
3. All request items included in skpaymentmentqueue,
4. Use skpaymenttransactionobseRver's paymentqueue: updatedtransactions: method to detect all completed purchases and send the purchased items.
5. Finally, use finishtransaction: to complete the transaction.

When a payment object is added to the payment queue, a persistent transaction object is created to store the object. After the payment is processed, the transaction is updated. In the program, an observer (observer) object is implemented to obtain the transaction update message. The observer should provide the purchased item to the user and then remove the transaction from the queue.

The following describes several classes used in the purchase process:
Skpayment
To collect payment information, first understand the payment object. The payment object contains the identifier of the product and the quantity of the product to be purchased (quantity is optional ). You can repeat the same payment object into the payment queue. Every such action is equivalent to an independent payment request.

You can disable the purchase feature in the settings program. Therefore, before the request is made, the program should first check whether the payment can be processed. Call the canmakepayments method of skpaymentqueue to check.

Skpaymentqueue
The payment queue is used to communicate with the app store. When a new payment object is added to the queue, store kit sends a request to the app store. Store kit will pop up a dialog box asking you if you are sure to buy. The completed transaction will be returned to the program's observer object.

Skpaymenttransaction
The transaction object is created every time a new payment is added to the queue. The transaction object contains some attributes that allow the program to determine the current transaction status.

You can obtain a list of transactions under review from the payment queue. However, it is more common to wait for the payment queue to notify the transaction status update.

SkpaymenttransactionobseRver
Implement skpaymenttransactionobse in the programRver protocol, and then use it as the observer of the skpaymentqueue object. The observer's primary responsibilities are to check the completed transactions, deliver the purchased content, and remove the completed transaction objects from the queue.

When the program starts, it should specify the corresponding observer object for the payment queue, instead of waiting until the user wants to buy the product. The transaction object will not be lost when the program exits. When the program restarts, store kit continues to execute unfinished transactions. Adding an observer object during program initialization ensures that all transactions are received by the Program (that is, if there is an incomplete transaction, if the program restarts, it will start again, if you add an observer later, some transaction information may be missed ).

Transaction information recovery (transactions)
After transaction is processed and removed from the queue, the program will not see them any more. If your program provides non-consumable or subscription-type products, you must provide the restore function so that users can store the purchase information on other devices.

Store kit provides built-in functions to re-store transaction information for non-consumable items. Call restorecompletedtransact of skpaymentqueueIons method to re-store. For non-consumable products that have previously completed transactions, Apple Store generates new transaction information for recovery. It contains the original transaction information. Your program can get this information and continue to unlock the purchased feature. When all previous transactions are restored, the paymentqueuerestorecompl of the observer object is called.EtedtransactionsfinishedMethod.

If a user tries to purchase a non-consumable item that has already been purchased, the procedure will receive a regular transaction information, rather than a restored transaction information. However, the user will not be charged again. Procedures should treat such transactions as original transactions.

Subscription and consumption products are not automatically restored by store kit. To recover these items, you must record the transaction information on your own server when the user purchases these items and provide a mechanism for the user's device to recover the transaction information.
Add the store function to the program
This chapter provides guidance on adding a purchase feature

Detailed process:

The preparation is to add storekit. framework.
The specific steps are as follows:

1. determine the type of goods sold within the program.
As mentioned earlier, there are limits on the new feature types that can be sold in programs. Store kit does not allow us to download new code. Your product can either work through the current Code (bundle type) or download through the server (of course, the download here is a data file, the Code is not allowed ). If you want to modify the source code, you can only upgrade it.

2. register products through iTunes connect
This step is required every time you add a new product. Each item requires a unique product identifier. App Store uses this identifier to find product information and process the payment process. The method for registering a product ID is similar to that for registering a program.

To learn how to create and register product information, see the "ITunes connect developer Guide" document.

3. Check whether payment can be made
You can disable the internal payment function. Before sending a payment request, the program should check whether the function is enabled. The program can check the settings before displaying the shop interface (the shop interface is not displayed if it is not enabled), or check the settings before sending a payment request, in this way, you can see the list of purchased items.

Example:
If ([skpaymentqueue canmakepayments])
{
    ... // Display a store to the user
}
Else
{
    ... // Warn the user that purchases are disabled.
}

4. Obtain product information
The program creates the skproductsrequest object, initializes it with the identifier of the product to be sold, and attaches the corresponding delegate object. The response to this request contains the localized information of available products.

// Send the request here
-(Void) requestproductdata
{
    Skproductsrequest * request = [[skproductsrequest alloc] initwithproductidentifieRS:
    [Nsset setwithobject: kmyfeatureidentifier];
    
    Request. Delegate = self;
    [Request start];
}

// This is the response's delegate Method
-(Void) productsrequest: (skproductsrequest *) Request
Didreceiveresponse: (skproductsresponse *) Response
{
    Nsarray * myproduct = response. Products;

    // Generate the store UI
    [Request autorelease];
}

5. Add an interface for displaying Products
Store kit does not provide interface classes. This interface needs to be designed and implemented by ourselves.

6. register an observer object for the payment queue
Your program needs to initialize a transaction observer object and specify it as the observer of the payment queue.

Code:

Mystoreobserver * Observer = [[mystoreobserver alloc] init];
[[Skpaymentqueue defaultqueue] addtransactionobserver: Observer];

The observer should be added when the program starts. The reason is as mentioned earlier. After the program is restarted, it will continue the previous unfinished transaction. In this case, adding the observer object will not miss the previous transaction information.

7. Execute the paymentqueue: updatedtransactions: Method in the mystoreobserver class.
This method will be called when new transactions are easy to create or when transactions are updated.

-(Void) paymentqueue: (skpaymentqueue *) queue updatedtransactions: (nsarray *) Transactions
{
    For (skpaymenttransaction * transaction in transactions)
    {
        Switch (transaction. transactionstate)
        {
            Case skpaymenttransactionstatEpurchased:
                [Self completetransaction: transaction];
                Break;
            Case skpaymenttransactionstatEfailed:
                [Self failedtransaction: transaction];
                Break;
            Case skpaymenttransactionstatErestored:
                [Self restoretransaction: transaction];
            Default:
                Break;
        }
    }
}

The above function calls the corresponding processing function for different transaction return states.

8. The observer object provides the corresponding content when the user successfully buys a product. The following method is called after the transaction is successful:
-(Void) completetransaction: (skpaymenttransaction *) Transaction
{
    // Your program needs to implement these two methods
    [Self recordtransaction: transaction];
    [Self providecontent: transaction. Payment. productidentifier];