StoreKitGuide(InAppPurchase)中文手册

1、Store Kit Guide(In App Purchase)中文手册一、In AppPurchase概览Store Kit代表App和App Store之间进行通信。程序将从App Store接收那些你想要提供的产品的信息，并将它们显示出来供用户购买。当用户需要购买某件产品时，程序调用StoreKit来收集购买信息。下图即为基本的store kit 模型：Store Kit的API只是为程序添加In AppPurchase功能的一小部分。你需要决定如何去记录那些你想要提交的产品，如何在程序中将商店功能展现给用户，还要考虑如何将用户购买的产品提交。本章的剩余部分会展示整个流程。Product

2、s产品可以是任意一项你想要出售的特性。产品在iTunes Connect中被组织，这和你添加一个新的App是一样的。支持的产品种类共有四种：1. 内容型。包括电子书，电子杂志，照片，插图，游戏关卡，游戏角色，和其他的数字内容。2. 扩展功能。这些功能已经包含在App内部。在未购买之前被锁定。例如，你可以在一个游戏程序中包含若干个小游戏，用户可以分别来购买这些游戏。3. 服务。允许程序对单次服务收费。比如录音服务。4. 订阅。支持对内容或服务的扩展访问。例如，你的程序可以每周提供财务信息或游戏门户网站的信息。应该设定一个合理的更新周期，以避免过于频繁的提示困扰用户。要记住：你将负责跟踪订阅的过期

3、信息，并且管理续费。App Store不会替你监视订阅的周期，也不提供自动收费的机制。In AppPurchase为创建产品提供了一种通用的机制，如何操作将由你负责。当你设计程序的时候，有以下几点需要注意：1. 你必须提供电子类产品和服务。不要使用In AppPurchase去出售实物和实际服务。2. 不能提供代表中介货币的物品，因为让用户知晓他们购买的商品和服务是很重要的。2. 服务器类型使用这终方式，要提供另外的服务器将产品发送给程序。 服务器交付适用于订阅、内容类商品和服务，因为商品可以作为数据发送，而不需改动程序束。 例如，一个游戏提供的新的内容（关卡等）。 Store Kit不会对服

4、务器端的设计和交互做出定义，这方面工作需要你来完成。 而且，Store Kit不提供验证用户身份的机制，你需要来设计。 如果你的程序需要以上功能，例如，纪录特定用户的订阅计划， 你需要自己来设计和实现。图1-3 展示了服务器类型的购买过程。1. 程序向服务器发送请求，获得一份产品列表。2. 服务器返回包含产品标识符的列表。3. 程序向App Store发送请求，得到产品的信息。4. App Store返回产品信息。5. 程序把返回的产品信息显示给用户（App的store界面）6. 用户选择某个产品7. 程序向App Store发送支付请求8. App Store处理支付请求并返回交易完成信息。

5、9. 程序从信息中获得数据，并发送至服务器。10. 服务器纪录数据，并进行审(我们的)查。11. 服务器将数据发给App Store来验证该交易的有效性。12. App Store对收到的数据进行解析，返回该数据和说明其是否有效的标识。13. 服务器读取返回的数据，确定用户购买的内容。14. 服务器将购买的内容传递给程序。Apple建议在服务器端存储产品标识，而不要将其存储在plist中。 这样就可以在不升级程序的前提下添加新的产品。在服务器模式下， 你的程序将获得交易（transaction）相关的信息，并将它发送给服务器。服务器可以验证收到的数据，并将其解码以确定需要交付的内容。 这个流程

6、将在“验证store收据”一节讨论。对于服务器模式，我们有安全性和可靠性方面的顾虑。 你应该测试整个环境来避免威胁。Secure Coding Guide文档中有相关的提示说明。虽然非消耗性商品可以用内置模式来恢复，订阅类商品必须通过服务器来恢复。你要负责纪录订阅信息、恢复数据。消耗类商品也可以通过服务器方式来纪录。例如，由服务器提供的一项服务， 你可能需要用户在多个设备上重新获得结果。（这段翻译的比较生硬，因为我个人也没有机会把各种类型的服务跑一遍，后续会检查并修改。希望大家一起来看看，欢迎补充。）取得产品信息要在程序内部显示“商店”，需要从App Store得到信息来购建界面。 本章详细讲

7、解如何从App Store获取产品信息。向App Store发送请求Store Kit提供了从App Store上请求数据的通用机制。 程序可以创建并初始化一个request对象， 为其附加delegate， 然后启动请求过程。请求将被发送到App Store，在那里被处理。 处理完成时， request对象的delegate方法将被异步调用，以获得请求的结果。 图2-1显示了请求的数据模型。如果程序在请求期间退出，则需要重新发送请求。下面讲解请求过程中用到的类：SKRequestSKRequest为request的抽象根类。SKRequestDelegateSKRequestDelegate

8、是一个protocol， 实现用以处理请求结果的方法，比如请求成功，或请求失败。发送获得产品信息的请求程序使用products request来获得产品的信息。 要完成这一过程，程序需创建一个request对象，其中会包含一个产品标识的列表。之前提到过，你的程序既可以内置产品列表，又可以通过外部服务器来获得。当发送请求时，产品标识会传送到App Store，App Store将会返回本地化信息（这些信息事先已经在iTunes Connect中设置好了），你将使用这些信息来购建内置商店的界面（显示商品名，描述，等等）。 图2-2显示了请求的过程。SKProductsRequest用来请求商品的信

9、息。 创建时，我们将需要显示的商品列表加入该对象。SKProductsRequestDelegate该protocol定义了处理App Store响应的方法。SKProductsResponseSKProductsResponse对象为App Store返回的响应信息。里面包含两个列表（当然是NSArray了）：一是经过验证有效的商品，property(nonatomic, readonly) NSArray *products另外一个是无法被识别的商品信息：property(nonatomic, readonly) NSArray * invalidProductIdentifiers有几种

10、原因将造成商品标识无法被识别，如拼写错误（当然），被标记为不可出售（unavailable for sale），或是对商品信息的改变没有传送到所有App Store的服务器。（这个原因不是很清楚，再议）。SKProductSKProduct对象包含了在App Store上注册的商品的本地化信息。购买商品当用户准备购买商品时，程序向App Store请求支付信息，然后App Store将会创建持久化的交易信息，并继续处理支付流程，即使用户重启程序，这个过程亦是如此。App Store同步待定交易的列表到程序中，并在交易状态发生改变时向程序发送更新的数据。收集支付信息要收集支付信息， 你的程序可以

11、创建一个payment的对象，将它放到支付队列中，如图3-1所示。1. 一个SKPayment的对象，包含了Sword的商品标识，并且制定购买数量为1。2. 使用addPayment:方法将SKPayment的对象添加到SKPaymentQueue里。3. SKPaymentmentQueue包含的所有请求商品，4. 使用SKPaymentTransactionObserver的paymentQueue: updatedTransactions: 方法来检测所有完成的购买，并发送购买的商品。5. 最后，使用finishTransaction:方法完成交易。当payment的对象被添加到支付队列

12、中的时候， 会创建一个持久保存的transaction对象来存放它。 当支付被处理后，transaction被更新。 程序中将实现一个观察者（observer）对象来获取transaction更新的消息。 观察者应该为用户提供购买的商品，然后将transaction从队列中移除。下面介绍在购买过程中用到的几个类：SKPayment要收集支付信息，先要了解一下支付对象。 支付对象包含了商品的标识（identifier）和要购买商品的数量（quantity）（数量可选）。你可以把同一个支付对象重复放入支付队列，每一次这样的动作都相当于一次独立的支付请求。用户可以在Settings程序中禁用购买的功

13、能。 因此在请求支付之前，程序应该首先检查支付是否可以被处理。 调用SKPaymentQueue的canMakePayments方法来检查。SKPaymentQueue支付队列用以和App Store之间进行通信。 当新的支付对象被添加到队列中的时候， Store Kit向App Store发送请求。 Store Kit将会弹出对话框询问用户是否确定购买。 完成的交易将会返回给程序的observer对象。SKPaymentTransactiontransaction对象在每次添加新的payment到队列中的时候被创建。 transaction对象包含了一些属性，可以让程序确定当前的交易状态。程

14、序可以从支付队列那里得到一份审核中的交易列表，但更常用的做法还是等待支付队列告知交易状态的更新。SKPaymentTransactionObserver在程序中实现SKPaymentTransactionObserver的协议，然后把它作为SKPaymentQueue对象的观察者。该观察者的主要职责是：检查完成的交易，交付购买的内容，和把完成后的交易对象从队列中移除。在程序一启动，就应该为支付队列指定对应的观察者对象，而不是等到用户想要购买商品的时候。 Transaction对象在程序退出时不会丢失。程序重启时， Store Kit继续执行未完成的交易。 在程序初始化的时候添加观察者对象，可以

15、保证所有的交易都被程序接收（也就时说，如果有未完成的transaction，如果程序重启，就重新开始了，如果稍候再添加观察者，就可能会漏掉部分交易的信息）。恢复交易信息（Transactions）当transaction被处理并从队列移除之后，正常情况下，程序就再也看不到它们了。 如果你的程序提供的是非消耗性的或是订阅类的商品，就必须提供restore的功能，使用户可以在其他设备上重新存储购买信息。Store Kit提供内建的功能来重新存储非消耗商品的交易信息。 调用SKPaymentQueue的restoreCompletedTransactions的方法来重新存储。对于那些之前已经完成交易

16、的非消耗性商品，Apple Store生成新的，用于恢复的交易信息。 它包含了原始的交易信息。你的程序可以拿到这个信息，然后继续为购买的功能解锁。 当之前所有的交易都被恢复时， 就会调用观察者对象的paymentQueueRestoreCompletedTransactionsFinished方法。如果用户试图购买已经买过的非消耗性商品，程序会收到一个常规的交易信息，而不是恢复的交易信息。但是用户不会被再次收费。程序 应把这类交易和原始的交易同等对待。订阅类服务和消耗类商品不会被Store Kit自动恢复。 要恢复这些商品，你必须在用户购买这些商品时，在你自己的服务器上记录这些交易信息， 并且

17、为用户的设备提供恢复交易信息的机制。在程序中添加Store功能本章为添加购买功能的指导详细流程：准备工作当然是添加StoreKit.framework了。然后是具体的步骤：1. 决定在程序内出售的商品的类型。之前提到过，程序内可以出售的新feature类型是有限制的。 Store Kit不允许我们下载新的代码。 你的商品要么可以通过当前的代码工作（bundle类型），要么可以通过服务器下载（当然，这里下载的为数据文件，代码是不可以的）。 如果要修改源代码，就只能老实的升级了。2. 通过iTunes Connect注册商品每次添加新商品的时候都需要执行这一步骤。 每个商品都需要一个唯一的商品标识

18、。 App Store通过这个标识来查找商品信息并处理支付流程。 注册商品标识的方法和注册程序的方法类似。要了解如何创建和注册商品信息，请参考“iTunes Connect Developer Guide”文档。3. 检测是否可以进行支付用户可以禁用在程序内部支付的功能。在发送支付请求之前，程序应该检查该功能是否被开启。程序可在显示商店界面之前就检查该设置（没启用就不显示商店界面了），也可以在用户发送支付请求前再检查，这样用户就可以看到可购买的商品列表了。例子：if(SKPaymentQueue canMakePayments)./Display a store to the userelse

19、./Warn the user that purchases are disabled.4. 获得商品的信息程序创建SKProductsRequest对象，用想要出售的商品的标识来初始化， 然后附加上对应的委托对象。 该请求的响应包含了可用商品的本地化信息。/这里发送请求- (void)requestProductDataSKProductsRequest *request = SKProductsRequest allocinitWithProductIdentifiers:NSSet setWithObject: kMyFeatureIdentifier;request.delegate

20、= self;request start;/这个是响应的delegate方法- (void)productsRequest: (SKProductsRequest *)requestdidReceiveResponse: (SKProductsResponse *)responseNSArray *myProduct = ducts;/生成商店的UIrequest autorelease;5. 添加一个展示商品的界面Store Kit不提供界面的类。 这个界面需要我们自己来设计并实现。6. 为支付队列（payment queue）注册一个观察者对象你的程序需要初始化一个

21、transaction observer对象并把它指定为payment queue的观察者。上代码：MyStoreObserver *observer = MyStoreObserver allocinit;SKPaymentQueue defaultQueueaddTransactionObserver: observer;应该在程序启动的时候就添加好观察者，原因前面说过，重启后程序会继续上次未完的交易，这时就添加观察者对象就不会漏掉之前的交易信息。7. 在MyStoreObserver类中执行paymentQueue: updatedTransactions: 方法。这个方法会在有新的交易

22、被创建，或者交易被更新的时候被调用。- (void)paymentQueue: (SKPaymentQueue *)queue updatedTransactions: (NSArray *)transactionsfor(SKPaymentTransaction * transaction in transactions)switch(transaction.transactionState)case SKPaymentTransactionStatePurchased:self completeTransaction: transaction;break;case SKPaymentTra

23、nsactionStateFailed:self failedTransaction: transaction;break;case SKPaymentTransactionStateRestored:self restoreTransaction: transaction;default:break;上面的函数针对不同的交易返回状态，调用对应的处理函数。8. 观察者对象在用户成功购买一件商品时，提供相应的内容，以下是在交易成功后调用的方法- (void) completeTransaction: (SKPaymentTransaction *)transaction/你的程序需要实现这两个方

24、法self recordTransaction: transaction;self provideContent: ductIdentifier;/将完成后的交易信息移出队列SKPaymentQueue defaultQueuefinishTransaction: transaction;交易成功的信息包含transactionIdentifier和transactionReceipt的属性。其中，transactionReceipt记录了支付的详细信息，这个信息可以帮助你跟踪、审(我们的)查交易，如果你的程序是用服务器来交付内容，transact

25、ionReceipt可以被传送到服务器，然后通过App Store验证交易。（之前提到的server模式，可以参考以前的图）9. 如果交易是恢复过来的（restore），我们用这个方法来处理：- (void) restoreTransaction: (SKPaymentTransaction *)transactionself recordTransaction: transaction;self provideContent: ductIdentifier;SKPaymentQueue defaultQueue finishTransaction

26、: transaction;这个过程完成购买的过程类似。 恢复的购买内容提供一个新的交易信息，这个信息包含了新的transaction的标识和receipt数据。 如果需要的话，你可以把这些信息单独保存下来，供追溯审(我们的)查之用。但更多的情况下，在交易完成时，你可能需要覆盖原始的transaction数据，并使用其中的商品标识。10. 交易过程失败的话，我们调用如下的方法：- (void)failedTransaction: (SKPaymentTransaction *)transactionif(transaction.error.code != SKErrorPaymentCance

27、lled)/在这类显示除用户取消之外的错误信息SKPaymentQueue defaultQueue finishTransaction: transaction;通常情况下，交易失败的原因是取消购买商品的流程。 程序可以从error中读出交易失败的详细信息。显示错误信息不是必须的，但在上面的处理方法中，需要将失败的交易从支付队列中移除。 一般来说，我们用一个对话框来显示错误信息，这时就应避免将用户取消购买这个error显示出来。11. 组织好程序内“商店”的UI。当用户选择一件商品时， 创建一个支付对象，并放到队列中。SKPayment *payment = SKPayment paymen

28、tWithProductIdentifier: kMyFeatureIdentifier;SKPaymentQueue defaultQueue addPayment: payment;如果你的商店支持选择同一件商品的数量，你可以设置支付对象的quantity属性SKMutablePayment *payment = SKMutablePayment paymentWithProductIdentifier: kMyFeatureIdentifier;payment.quantity = 3;SKPaymentQueue defaultQueue addPayment: payment;下一步

29、：本章中所示代码可用于内置型商品模式(Built-in)。 如果你的程序要使用服务器来发布商品，你需要负责设计和执行iPhone程序和你的服务器之间的通信。服务器应该验证数据并为程序提供内容。验证store的收据使用服务器来交付内容，我们还需要做些额外的工作来验证从Store Kit发送的收据信息。重要信息：来自Store的收据信息的格式是专用的。 你的程序不应直接解析这类数据。可使用如下的机制来取出其中的信息。验证App Store返回的收据信息当交易完成时，Store Kit告知payment observer这个消息，并返回完成的transaction。 SKPaymentTransac

30、tion的transactionReceipt属性就包含了一个经过签名的收据信息，其中记录了交易的关键信息。你的服务器要负责提交收据信息来确定其有效性，并保证它未经过篡改。 这个过程中，信息被以JSON数据格式发送给App Store，App Store也以JSON的格式返回数据。（大家可以先了解一下JSON的格式）验证收据的过程：1. 从transaction的transactionReceipt属性中得到收据的数据，并以base64方式编码。2. 创建JSON对象，字典格式，单键值对，键名为receipt-data， 值为上一步编码后的数据。效果为:receipt-data: (编码后的数

31、据)3. 发送HTTP POST的请求，将数据发送到App Store，其地址为:4. App Store的返回值也是一个JSON格式的对象，包含两个键值对， status和receipt:status: 0,receipt: 如果status的值为0， 就说明该receipt为有效的。 否则就是无效的。App Store的收据发送给App Store的收据数据是通过对transaction中对应的信息编码而创建的。 当App Store验证收据时， 将从其中解码出数据，并以receipt的键返回。 返回的响应信息是JSON格式，被包含在SKPaymentTransaction的对象中（tra

32、nsactionReceipt属性）。Server可通过这些值来了解交易的详细信息。 Apple建议只发送receipt数据到服务器并使用receipt数据验证和获得交易详情。 因为App Store可验证收据信息，返回信息，保证信息不被篡改，这种方式比同时提交receipt和transaction的数据要安全。（这段得再看看）表5-1为交易信息的所有键，很多的键都对应SKPaymentTransaction的属性。备注：一些键取决于你的程序是链接到App Store还是测试用的Sandbox环境。更多关于sandbox的信息，请查看Testing a Store一章。Table 5-1 购买信息的键：键名描述quantity 购买商品的数量。对应SKPayment对象中的quantity属性product_id商品的标识，对应SKPayment对象的productIdentifier属性。transaction_id交易的标识，对应SKPaym