[cocos2dx 3.0 + iap]中文文档

一、In App Purchase概览
Store Kit代表App和App Store之间进行通信。法度将从App Store接管那些你想要供给的产品的信息，并将它们显示出来供用户购买。
当用户须要购买某件产品时，法度调用StoreKit来收集购买信息。 下图即为根蒂根基的store kit 模型：
Store Kit的API只是为法度添加In App Purchase功能的一小项目组。你须要决意如何去记录那些你想要提交的产品，如安在法度中将市廛功能显现给用户，
还要推敲如何将用户购买的产品 提交。本章的残剩项目组会显现全部流程。
Products
产品可所以随便率性一项你想要的特点。产品在iTunes Connect中被组织，这和你添加一个新的App是一样的。支撑的产品种类共有四种：
1. 内容型。包含电子书，电子杂志，照片，插图，游戏关卡，游戏角色，和其他的数字内容。
2. 扩大功能。这些功能已经包含在App内部。在未购买之前被锁定。例如，你可以在一个游戏法度中包含若干个小游戏，用户可以分别来购买这些游戏。
3. 办事。容许法度对单次办事收费。比如灌音办事。
4. 订阅。支撑对内容或办事的扩大接见。例如，你的法度可以每周供给财务信息或游戏门户网站的信息。应当设定一个公道的更新周期，以避免过于频繁的
提 示困扰用户。要记住：你将负责跟踪订阅的过期信息，并且经管续费。App Store不会替你把守订阅的周期，也不供给主动收费的机制。
In App Purchase为创建产品供给了一种通用的机制，如何操纵将由你负责。当你设计法度的时辰，有以下几点须要重视：
1. 你必须供给电子类产品和办事。不要应用In App Purchase 去什物和实际办事。
2. 不克不及供给代表中介货币的物品，因为让用户知晓他们购买的商品和办事是很首要的。
经由过程App Store注册产品
每个你想要的产品都必须先经由过程iTunes Connect在App Store注册。你需供给产品的名称，描述，价格和其他在法度顶用到的元数据。
需为产品指定独一的标识符。当你的法度哄骗Store Kit和App Store通信时，会应用产品标识来取回产品的信息。若是用户购买某个商品时，法度可以用该标识来将产品标注为“已购买”。
App Store将前面提到过的产品种类简化为以下三种：
1. 消费性商品。 该类商品在须要时被单次购买。比如，单次办事。
2. 非消费性商品。 该类商品只需被某个用户购买一次，一旦被购买，和该用户iTunes 账户接洽关系的设备都可以应用此商品。Store Kit为在多个设备上从头存储非消费性商品供给了内置的支撑。
3. 订阅类。订阅类商品拥有以上两种类型的特点。和消费性商品一样，订阅类商品可以被多次购买； 你可以在法度内部参加本身的订阅规划更新机制。 别的，订阅类商品必须供给给和某一用户接洽关系的所有设备。In App Purchase期望订阅类商品可以经由过程外部办事器交付。你必须为多个设备的订阅办事供给响应的支撑。
关于注册产品的具体信息，请参考 iTunes Connect Developer Guide文档。
交付体式格式
交付机制在法度In App Purchase的设计和实现种有很首要的意义。有两种根蒂根基的模型可以用来交付产品：内置类型（Built-in model）和办事器类型（Server model）。 不管应用那种模型，你都须要保护产品列表，并包管当用户购买后，成功的交付产品。
1. 内置产品类型
应用这种模型。 须要交付的产品已经在法度内部。 这种体式格式凡是用在一些被锁定的功能上。 也可以用来交付在法度束（App Bundle）中的内容。 该体式格式的一个首要的长处是你可以及时的给客户交付产品，大多半的内置产品应为非消费性商品。
重视：In App Purchase不供给购买补丁的功能。 若是须要更改app的bundle，你必须向App Store提交新的app版本。
为 了标识产品，法度要在bundle中存储产品的标识符。内置模式下，Apple建议应用plist来记载产品的标识符。 内容类应用可以应用调和体式格式很便利的添加新的内容，而不批改法度本身。（原话为： Content-driven applications can use this to add new content without modifying the source for your application，不是很懂，感触感染应当是说类似是用plist来经管产品列表，是以就不须要在添加新产品的时辰批改法度了。再议。。。）
当 成功购买产品后，法度应将锁定的功能解锁，供给给用户。 解锁的最简单体式格式是批改法度偏好设置（Application Preferences）。 当用户备份数据的时辰，法度偏好设置也会随之备份。 法度可能须要建议用户在购买产品后备份以免丧失购买的内容。
图1-2显示了 交付内置型产品的流程。
1. 法度经由过程bundle存储的plist文件获得产品标识符的列表。
2. 法度向App Store发送恳求，获得产品的信息。
3. App Store返回产品信息。
4. 法度把返回的产品信息显示给用户（App的store界面）
5. 用户选择某个产品
6. 法度向App Store发送付出恳求
7. App Store处理惩罚付出恳求并返回交易完成信息。
8. App获取信息并供给内容给用户。
:built-in.png

X

2. 办事器类型
应用这种体式格式，要供给别的的办事器将产品发送给法度。 办事器交付实用于订阅、内容类商品和办事，因为商品可以作为数据发送，而不需批改法度束。 例如，一个游戏供给的新的内容（关卡等）。 Store Kit不会对办事器端的设计和交互做出定义，这方面工作须要你来完成。 并且，Store Kit不供给验证用户身份的机制，你须要来设计。 若是你的法度须要以上功能，例如，记载特定用户的订阅规划， 你须要本身来设计和实现。
图1-3 显现了办事器类型的购买过程。

1. 法度向办事器发送恳求，获得一份产品列表。
2. 办事器返回包含产品标识符的列表。
3. 法度向App Store发送恳求，获得产品的信息。
4. App Store返回产品信息。
5. 法度把返回的产品信息显示给用户（App的store界面）
6. 用户选择某个产品
7. 法度向App Store发送付出恳求
8. App Store处理惩罚付出恳求并返回交易完成信息。
9. 法度从信息中获得数据，并发送至办事器。
10. 办事器记载数据，并进行审（我们的）查。
11. 办事器将数据发给App Store来验证该交易的有效性。
12. App Store对收到的数据进行解析，返回该数据和申明其是否有效的标识。
13. 办事器读取返回的数据，断定用户购买的内容。
14. 办事器将购买的内容传递给法度。
Apple建议在办事器端存储产品标识，而不要将其存储在plist中。 如许就可以在不进级法度的前提下添加新的产品。
在办事器模式下， 你的法度将获得交易（transaction）相干的信息，并将它发送给办事器。办事器可以验证收到的数据，并将其解码以断定须要交付的内容。 这个流程将在“验证store收据”一节评论辩论。
对于办事器模式，我们有安然性和靠得住性方面的顾虑。 你应当测试全部景象来避免威逼。《Secure Coding Guide》文档中有相干的提示申明。
固然非消费性商品可以用内置模式来 恢复，订阅类商品必须经由过程办事器来恢复。你要负责记载订阅信息、恢复数据。
消费类商品也可以经由过程办事器体式格式来记载。例如，由办事器供给的一项服 务， 你可能须要用户在多个设备上从头获得成果。
取得产品信息
要在法度内部显示“市廛”，须要从App Store获得信息来购建界面。 本章具体讲解如何从App Store获取产品信息。
向App Store发送恳求
Store Kit供给了从App Store上恳求数据的通用机制。 法度可以创建并初始化一个request对象， 为其附加delegate， 然后启动恳求过程。恳求将被发送到App Store，在那边被处理惩罚。 处理惩罚完成时， request对象的delegate办法将被异步调用，以获得恳求的成果。 图2-1显示了恳求的数据模型。

若是法度在恳求时代退出，则须要从头发送恳求。
下面讲解恳求过程顶用到的类：
SKRequest
SKRequest 为request的抽象根类。
SKRequestDelegate
SKRequestDelegate是一个protocol， 实现用以处理惩罚恳求成果的办法，比如恳求成功，或恳求失败。
发送获得产品信息的恳求
法度应用products request来获得产品的信息。 要完成这一过程，法度需创建一个request对象，此中会包含一个产品标识的列表。之前提到过，你的法度既可以内置产品列表，又可以经由过程外部办事器来获 得。
当发送恳求时，产品标识会传送到App Store，App Store将会返回本地化信息（这些信息事先已经在iTunes Connect中设置好了），你将应用这些信息来购建内置市廛的界面（显示商品名，描述，等等）。 图2-2显示了恳求的过程。

SKProductsRequest
用来恳求商品的信息。 创建时，我们将须要显示的商品列表参加该对象。
SKProductsRequestDelegate
该protocol定义了处 理App Store响应的办法。
SKProductsResponse
SKProductsResponse对象为App Store返回的响应信息。里面包含两个列表（当然是NSArray了）：一是经过验证有效的商品，
＠property（nonatomic， readonly） NSArray *products
别的一个是无法被识此外商品信息：
＠property（nonatomic， readonly） NSArray * invalidProductIdentifiers
有几种原因将造成商品标识无法被辨认，如拼写错误 （当然），被标识表记标帜为不成（unavailable for sale），或是对商品信息的改变没有传送到所有App Store的办事器。（这个原因不是很清楚，再议）。
SKProduct
SKProduct对象包含了在App Store上注册的商品的本地化信息。
购买商品
当用户筹办购买商品时，法度向App Store恳求付出信息，然后App Store将会创建持久化的交易信息，并持续处理惩罚付出流程，即应用户重启法度，这个过程亦是如此。App Store同步待定交易的列表到法度中，并在交易状况产生改变时向法度发送更新的数据。
收集付出信息
要收集付出信息， 你的法度可以创建一个payment的对象，将它放到付出队列中，如图3-1所示。

1. 一个SKPayment的对象，包含了""Sword""的商品标识，并且制订购买数量为1。
2. 应用addPayment:办法将SKPayment的对象添加到SKPaymentQueue里。
3. SKPaymentmentQueue包含的所有恳求商品，
4. 应用SKPaymentTransactionObserver的paymentQueue: dTransactions: 办法来检测所有完成的购买，并发送购买的商品。
5. 最后，应用finishTransaction:办法完成交易。
当 payment的对象被添加到付出队列中的时辰， 会创建一个持久保存的transaction对象来存放它。 当付出被处理惩罚后，transaction被更新。 法度中将实现一个调查者（observer）对象来获取transaction更新的消息。 调查者应当为用户供给购买的商品，然后将transaction从队列中移除。
下面介绍在购买过程顶用到的几个类：
SKPayment
要 收集付出信息，先要懂得一下付出对象。 付出对象包含了商品的标识（identifier）和要购买商品的数量（quantity）（数量可选）。你可以把同一个付出对象反复放入付出队列，，每 一次如许的动作都相当于一次自力的付出恳求。
用户可以在Settings法度中禁用购买的功能。 是以在恳求付出之前，法度应当起首搜检付出是否可以被处理惩罚。 调用SKPaymentQueue的canMakePayments办法来搜检。
SKPaymentQueue
支 付队列用以和App Store之间进行通信。 当新的付出对象被添加到队列中的时辰， Store Kit向App Store发送恳求。 Store Kit将会弹出对话框询问用户是否断定购买。 完成的交易将会返回给法度的observer对象。
SKPaymentTransaction
transaction 对象在每次添加新的payment到队列中的时辰被创建。 transaction对象包含了一些属性，可以让法度断定当前的交易状况。
程 序可以从付出队列那边获得一份审核中的交易列表，但更常用的做法还是守候付出队列告诉交易状况的更新。
SKPaymentTransactionObserver
在 法度中实现SKPaymentTransactionObserver的和谈，然后把它作为SKPaymentQueue对象的调查者。该调查者的首要职 责是：搜检完成的交易，交付购买的内容，和把完成后的交易对象从队列中移除。
在法度一启动，就应当为付出队列指定对应的调查者对象，而不 是比及用户想要购买商品的时辰。 Transaction对象在法度退出时不会丧失。法度重启时， Store Kit持续履行未完成的交易。 在法度初始化的时辰添加调查者对象，可以包管所有的交易都被法度接管（也就时说，若是有未完成的transaction，若是法度重启，就从头开端了，如 果稍候再添加调查者，就可能会漏掉项目组交易的信息）。
恢复交易信息（Transactions）
当 transaction被处理惩罚并从队列移除之后，正常景象下，法度就再也看不到它们了。 若是你的法度供给的长短消费性的或是订阅类的商品，就必须供给restore的功能，应用户可以在其他设备上从头存储购买信息。
Store Kit供给内建的功能来从头存储非消费商品的交易信息。 调用SKPaymentQueue的restoreCompletedTransactions的办法来从头存储。对于那些之前已经完成交易的非消费性商 品，Apple Store生成新的，用于恢复的交易信息。 它包含了原始的交易信息。你的法度可以拿到这个信息，然后持续为购买的功能解锁。 当之前所有的交易都被恢复时， 就会调用调查者对象的paymentQueueRestoreCompletedTransactionsFinished办法。
若是用 户试图购买已经买过的非消费性商品，法度会收到一个常规的交易信息，而不是恢复的交易信息。然则用户不会被再次收费。法度 应把这类交易和原始的交易一律对待。
订阅类办事和消费类商品不会被Store Kit主动恢复。 要恢复这些商品，你必须在用户购买这些商品时，在你本身的办事器上记录这些交易信息， 并且为用户的设备供给恢复交易信息的机制。
在法度中添加Store功能
本章为添加购买功能的领导
具体流程：
筹办工作当然是添加 StoreKit.framework了。
然后是具体的步调：
1. 决意在法度内的商品的类型。
之前提到过，法度内 可以的新feature类型是有限制的。 Store Kit不容许我们新的代码。 你的商品要么可以经由过程当前的代码工作（bundle类型），要么可以经由过程办事器（当然，这里的为数据文件，代码是不成以的）。 若是要批改源代码，就只能忠诚的进级了。
2. 经由过程iTunes Connect注册商品
每次添加新商品的时辰都须要履行这一步 骤。 每个商品都须要一个独一的商品标识。 App Store经由过程这个标识来查找商品信息并处理惩罚付出流程。 注册商品标识的办法和注册法度的办法类似。
要 懂得如何创建和注册商品信息，请参考“iTunes Connect Developer Guide”文档。
3. 检测是否可以进行付出
用户可以禁用在法度内部付出的功能。在发送付出恳求之前，法度应当搜检该功能是否被开启。法度可在显示市廛界面之前就搜检该 设置（没启用就不显示市廛界面了），也可以在用户发送付出恳求前再搜检，如许用户就可以看到可购买的商品列表了。
例子：
if（[SKPaymentQueue canMakePayments]）
{
...//Display a store to the user
}
else
{
...//Warn the user that purchases are disabled.
}
4. 获得商品的信息
法度创建 SKProductsRequest对象，用想要的商品的标识来初始化， 然后附加上对应的委托对象。 该恳求的响应包含了可用商品的本地化信息。
// 这里发送恳求
- （void）requestProductData
{
SKProductsRequest *request= [[SKProductsRequest alloc]initWithProductIdentifiers:
[NSSet setWithObject: kMyFeatureIdentifier]];
request.delegate = self;
[request start];
}
//这个是响应的delegate办法
- （void）productsRequest: （SKProductsRequest *）request
didReceiveResponse: （SKProductsResponse *）response
{
NSArray *myProduct = response.products;
//生成市廛的UI
[request autorelease];
}
5. 添加一个显现商品的界面
Store Kit不供给界面的类。 这个界面须要我们本身来设计并实现。
6. 为付出队列（payment queue）注册一个调查者对象
你的法度须要初始化一个transaction observer对象并把它指定为payment queue的调查者。
上代码：
MyStoreObserver *observer = [[MyStoreObserver alloc]init];
[[SKPaymentQueue defaultQueue]addTransactionObserver: observer];
应当在法度启动的时辰就添加好调查 者，原因前面说过，重启后法度会持续前次未完的交易，这时就添加调查者对象就不会漏掉之前的交易信息。
7. 在MyStoreObserver类中履行paymentQueue: dTransactions: 办法。
这个办在有新的交 易被创建，或者交易被更新的时辰被调用。
- （void）paymentQueue: （SKPaymentQueue *）queue dTransactions: （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;
}
}
}
上 面的函数针对不合的交易返回状况，调用对应的处理惩罚函数。
8. 调查者对象在用户成功购买一件商品时，供给响应的内容，以下是在交易成功后调用的办法
- （void） completeTransaction: （SKPaymentTransaction *）transaction
{
//你 的法度须要实现这两个办法
[self recordTransaction: transaction];
[self provideContent: transaction.payment.productIdentifier];
// 将完成后的交易信息移出队列
[[SKPaymentQueue defaultQueue]finishTransaction: transaction];
}
交易成功的信息包含transactionIdentifier和 transactionReceipt的属性。此中，transactionReceipt记录了付出的具体信息，这个信息可以帮助你跟踪、审（我们的） 查交易，若是你的法度是用办事器来交付内容，transactionReceipt可以被传送到办事器，然后经由过程App Store验证交易。（之前提到的server模式，可以参考以前的图）
9. 若是交易是恢复过来的（restore），我们用这个办法来处理惩罚：
- （void） restoreTransaction: （SKPaymentTransaction *）transaction
{
[self recordTransaction: transaction];
[self provideContent: transaction.payment.productIdentifier];
[[SKPaymentQueue defaultQueue] finishTransaction: transaction];
}
这个过程完成购买的过程类似。 恢复的购买内容供给一个新的交易信息，这个信息包含了新的transaction的标识和receipt数据。 若是须要的话，你可以把这些信息零丁保存下来，供追溯审（我们的）查之用。但更多的景象下，在交易完成时，你可能须要覆盖原始的transaction数 据，并应用此中的商品标识。
10. 交易过程失败的话，我们调用如下的办法：
- （void）failedTransaction: （SKPaymentTransaction *）transaction
{
if（transaction.error.code != SKErrorPaymentCancelled）
{
//在这类显示除用户作废之外的错误信息
}
[[SKPaymentQueue defaultQueue] finishTransaction: transaction];
}
凡是景象下，交易失败的原 因是作废购买商品的流程。 法度可以从error中读出交易失败的具体信息。
显示错误信息不是必须的，但在上方的处理惩罚办法中，须要将失败 的交易从付出队列中移除。 一般来说，我们用一个对话框来显示错误信息，这时就应避免将用户作废购买这个error显示出来。
11. 组织好法度内“市廛”的UI。当用户选择一件商品时， 创建一个付出对象，并放到队列中。
SKPayment *payment = [SKPayment paymentWithProductIdentifier: kMyFeatureIdentifier];
[[SKPaymentQueue defaultQueue] addPayment: payment];
若是你的市廛支撑选择同一件商品的数量，你可以设置付出对象 的quantity属性
SKMutablePayment *payment = [SKMutablePayment paymentWithProductIdentifier: kMyFeatureIdentifier];
payment.quantity = 3;
[[SKPaymentQueue defaultQueue] addPayment: payment];
下 一步：
本章中所示代码可用于内置型商品模式（Built-in）。 若是你的法度要应用办事器来公布商品，你须要负责设计和履行iPhone法度和你的办事器之间的通信。办事器应当验证数据并为法度供给内容。
验证store的收据
应用办事器来交付内容，我们还须要做些额外的工作来验证从Store Kit发送的收据信息。
首要信息：来自Store的收据信息的格局是专用的。 你的法度不该直接解析这类数据。可应用如下的机制来取出此中的信息。
验证App Store返回的收据信息
当交易完成时，Store Kit告诉payment observer这个消息，并返回完成的transaction。 SKPaymentTransaction的transactionReceipt属性就包含了一个经过的收据信息，此中记录了交易的关键信息。你的办事器要负责提交收据信息来断定其有效性，并包管它未经过批改。 这个过程中，信息被以JSON数据格局发送给App Store，App Store也以JSON的格局返回数据。
（大师可以先懂得一下JSON的格局）
验证收据的过程：
1. 从transaction的transactionReceipt属性中获得收据的数据，并以base64体式格式编码。
2. 创建JSON对象，字典格局，单键值对，键名为""receipt-data""， 值为上一步编码后的数据。结果为:
{
""receipt-data"" : ""（编码后的数据）""
}
3. 发送HTTP POST的恳求，将数据发送到App Store，其地址为:
https://buy.itunes.apple.com/verfyReceipt
4. App Store的返回值也是一个JSON格局的对象，包含两个键值对， status和receipt:
{
""status"" : 0，
""receipt"" : { … }
}
若是status的值为0， 就申明该receipt为有效的。 不然就是无效的。
App Store的收据
发送给App Store的收据数据是经由过程对transaction中对应的信息编码而创建的。 当App Store验证收据时， 将从此中解码出数据，并以""receipt""的键返回。 返回的响应信息是JSON格局，被包含在SKPaymentTransaction的对象中（transactionReceipt属性）。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 交易的标识，对应 SKPaymentTransaction的transactionIdentifier属性
purchase_date 交易的日期，对 应SKPaymentTransaction的transactionDate属性
original_-transaction_id 对 于恢复的transaction对象，该键对应了原始的transaction标识
original_purchase_-date 对于 恢复的transaction对象，该键对应了原始的交易日期
app_item_id App Store用来标识法度的字符串。一个办事器可能须要支撑多个server的付出功能，可以用这个标识来区分法度。链接sandbox用来测试的法度的不 到这个值，是以该键不存在。
version_external_-identifier 用来标识法度修订数。该键在sandbox景象下 不存在
bid iPhone法度的bundle标识
bvrs iPhone法度的版本号
测试Store功能
开 发过程中，我们须要测试付出功能以包管其工作正常。然而，我们不在测试时对用户收费。 Apple供给了sandbox的景象供我们测试。
备 注：Store Kit在模仿器上无法运行。 当在模仿器上运行Store Kit的时辰，接见payment queue的动作会打出一条警告的log。测试store功能必须在真机长进行。
Sandbox景象
应用Sandbox景象的 话，Store Kit并没有链接到真实的App Store，而是链接到专门的Sandbox景象。 SandBox的内容和App Store一致，只是它不履行真实的付出动作。 它会返回交易成功的信息。 Sandbox应用专门的iTunes Connect测试 账户。不克不及应用正式的iTunes Connect账户来测试。
要测试法度，须要创建一个专门的测试账户。你至少须要为法度的每个区域创 建至少一个测试账户。具体信息，请查看iTunes Connect Developer Guide文档。
在Sandbox景象中测试
步 骤：
1. 在测试的iPhone上退出iTunes账户
Settings中可能会记录之前登录的账户，进入并退出。
首要 信息：不克不及在Settings 法度中经由过程测试账户登录。
2. 运行法度
当你在法度的store中购买商品后，Store kit提示你去验证交易。用测试账户登录，并核准付出。 如许虚拟的交易就完成了。
在Sandbox中验证收据
验证的URL不合 了：
NSURL *sandboxStoreURL = [[NSURL alloc]initWithString:
＠""https://sandbox.itunes.apple.com/verifyReceipt""];
From：http://www.cocoachina.com/bbs/read.php？tid-24738-page-1.html