StoreKitGuide(InAppPurchase)中文手冊

1、Store Kit Guide(In App Purchase)中文手冊一、In AppPurchase概覽Store Kit代表App和App Store之間進行通信。程序?qū)腁pp Store接收那些你想要提供的產(chǎn)品的信息，并將它們顯示出來供用戶購買。當用戶需要購買某件產(chǎn)品時，程序調(diào)用StoreKit來收集購買信息。下圖即為基本的store kit 模型：Store Kit的API只是為程序添加In AppPurchase功能的一小部分。你需要決定如何去記錄那些你想要提交的產(chǎn)品，如何在程序中將商店功能展現(xiàn)給用戶，還要考慮如何將用戶購買的產(chǎn)品提交。本章的剩余部分會展示整個流程。Product

2、s產(chǎn)品可以是任意一項你想要出售的特性。產(chǎn)品在iTunes Connect中被組織，這和你添加一個新的App是一樣的。支持的產(chǎn)品種類共有四種：1. 內(nèi)容型。包括電子書，電子雜志，照片，插圖，游戲關(guān)卡，游戲角色，和其他的數(shù)字內(nèi)容。2. 擴展功能。這些功能已經(jīng)包含在App內(nèi)部。在未購買之前被鎖定。例如，你可以在一個游戲程序中包含若干個小游戲，用戶可以分別來購買這些游戲。3. 服務(wù)。允許程序?qū)未畏?wù)收費。比如錄音服務(wù)。4. 訂閱。支持對內(nèi)容或服務(wù)的擴展訪問。例如，你的程序可以每周提供財務(wù)信息或游戲門戶網(wǎng)站的信息。應(yīng)該設(shè)定一個合理的更新周期，以避免過于頻繁的提示困擾用戶。要記住：你將負責跟蹤訂閱的過期

3、信息，并且管理續(xù)費。App Store不會替你監(jiān)視訂閱的周期，也不提供自動收費的機制。In AppPurchase為創(chuàng)建產(chǎn)品提供了一種通用的機制，如何操作將由你負責。當你設(shè)計程序的時候，有以下幾點需要注意：1. 你必須提供電子類產(chǎn)品和服務(wù)。不要使用In AppPurchase去出售實物和實際服務(wù)。2. 不能提供代表中介貨幣的物品，因為讓用戶知曉他們購買的商品和服務(wù)是很重要的。2. 服務(wù)器類型使用這終方式，要提供另外的服務(wù)器將產(chǎn)品發(fā)送給程序。 服務(wù)器交付適用于訂閱、內(nèi)容類商品和服務(wù)，因為商品可以作為數(shù)據(jù)發(fā)送，而不需改動程序束。 例如，一個游戲提供的新的內(nèi)容（關(guān)卡等）。 Store Kit不會對服

4、務(wù)器端的設(shè)計和交互做出定義，這方面工作需要你來完成。 而且，Store Kit不提供驗證用戶身份的機制，你需要來設(shè)計。 如果你的程序需要以上功能，例如，紀錄特定用戶的訂閱計劃， 你需要自己來設(shè)計和實現(xiàn)。圖1-3 展示了服務(wù)器類型的購買過程。1. 程序向服務(wù)器發(fā)送請求，獲得一份產(chǎn)品列表。2. 服務(wù)器返回包含產(chǎn)品標識符的列表。3. 程序向App Store發(fā)送請求，得到產(chǎn)品的信息。4. App Store返回產(chǎn)品信息。5. 程序把返回的產(chǎn)品信息顯示給用戶（App的store界面）6. 用戶選擇某個產(chǎn)品7. 程序向App Store發(fā)送支付請求8. App Store處理支付請求并返回交易完成信息。

5、9. 程序從信息中獲得數(shù)據(jù)，并發(fā)送至服務(wù)器。10. 服務(wù)器紀錄數(shù)據(jù)，并進行審(我們的)查。11. 服務(wù)器將數(shù)據(jù)發(fā)給App Store來驗證該交易的有效性。12. App Store對收到的數(shù)據(jù)進行解析，返回該數(shù)據(jù)和說明其是否有效的標識。13. 服務(wù)器讀取返回的數(shù)據(jù)，確定用戶購買的內(nèi)容。14. 服務(wù)器將購買的內(nèi)容傳遞給程序。Apple建議在服務(wù)器端存儲產(chǎn)品標識，而不要將其存儲在plist中。 這樣就可以在不升級程序的前提下添加新的產(chǎn)品。在服務(wù)器模式下， 你的程序?qū)@得交易（transaction）相關(guān)的信息，并將它發(fā)送給服務(wù)器。服務(wù)器可以驗證收到的數(shù)據(jù)，并將其解碼以確定需要交付的內(nèi)容。 這個流程

6、將在“驗證store收據(jù)”一節(jié)討論。對于服務(wù)器模式，我們有安全性和可靠性方面的顧慮。 你應(yīng)該測試整個環(huán)境來避免威脅。Secure Coding Guide文檔中有相關(guān)的提示說明。雖然非消耗性商品可以用內(nèi)置模式來恢復(fù)，訂閱類商品必須通過服務(wù)器來恢復(fù)。你要負責紀錄訂閱信息、恢復(fù)數(shù)據(jù)。消耗類商品也可以通過服務(wù)器方式來紀錄。例如，由服務(wù)器提供的一項服務(wù)， 你可能需要用戶在多個設(shè)備上重新獲得結(jié)果。（這段翻譯的比較生硬，因為我個人也沒有機會把各種類型的服務(wù)跑一遍，后續(xù)會檢查并修改。希望大家一起來看看，歡迎補充。）取得產(chǎn)品信息要在程序內(nèi)部顯示“商店”，需要從App Store得到信息來購建界面。 本章詳細講

7、解如何從App Store獲取產(chǎn)品信息。向App Store發(fā)送請求Store Kit提供了從App Store上請求數(shù)據(jù)的通用機制。 程序可以創(chuàng)建并初始化一個request對象， 為其附加delegate， 然后啟動請求過程。請求將被發(fā)送到App Store，在那里被處理。 處理完成時， request對象的delegate方法將被異步調(diào)用，以獲得請求的結(jié)果。 圖2-1顯示了請求的數(shù)據(jù)模型。如果程序在請求期間退出，則需要重新發(fā)送請求。下面講解請求過程中用到的類：SKRequestSKRequest為request的抽象根類。SKRequestDelegateSKRequestDelegate

8、是一個protocol， 實現(xiàn)用以處理請求結(jié)果的方法，比如請求成功，或請求失敗。發(fā)送獲得產(chǎn)品信息的請求程序使用products request來獲得產(chǎn)品的信息。 要完成這一過程，程序需創(chuàng)建一個request對象，其中會包含一個產(chǎn)品標識的列表。之前提到過，你的程序既可以內(nèi)置產(chǎn)品列表，又可以通過外部服務(wù)器來獲得。當發(fā)送請求時，產(chǎn)品標識會傳送到App Store，App Store將會返回本地化信息（這些信息事先已經(jīng)在iTunes Connect中設(shè)置好了），你將使用這些信息來購建內(nèi)置商店的界面（顯示商品名，描述，等等）。 圖2-2顯示了請求的過程。SKProductsRequest用來請求商品的信

9、息。 創(chuàng)建時，我們將需要顯示的商品列表加入該對象。SKProductsRequestDelegate該protocol定義了處理App Store響應(yīng)的方法。SKProductsResponseSKProductsResponse對象為App Store返回的響應(yīng)信息。里面包含兩個列表（當然是NSArray了）：一是經(jīng)過驗證有效的商品，property(nonatomic, readonly) NSArray *products另外一個是無法被識別的商品信息：property(nonatomic, readonly) NSArray * invalidProductIdentifiers有幾種

10、原因?qū)⒃斐缮唐窐俗R無法被識別，如拼寫錯誤（當然），被標記為不可出售（unavailable for sale），或是對商品信息的改變沒有傳送到所有App Store的服務(wù)器。（這個原因不是很清楚，再議）。SKProductSKProduct對象包含了在App Store上注冊的商品的本地化信息。購買商品當用戶準備購買商品時，程序向App Store請求支付信息，然后App Store將會創(chuàng)建持久化的交易信息，并繼續(xù)處理支付流程，即使用戶重啟程序，這個過程亦是如此。App Store同步待定交易的列表到程序中，并在交易狀態(tài)發(fā)生改變時向程序發(fā)送更新的數(shù)據(jù)。收集支付信息要收集支付信息， 你的程序可以

11、創(chuàng)建一個payment的對象，將它放到支付隊列中，如圖3-1所示。1. 一個SKPayment的對象，包含了Sword的商品標識，并且制定購買數(shù)量為1。2. 使用addPayment:方法將SKPayment的對象添加到SKPaymentQueue里。3. SKPaymentmentQueue包含的所有請求商品，4. 使用SKPaymentTransactionObserver的paymentQueue: updatedTransactions: 方法來檢測所有完成的購買，并發(fā)送購買的商品。5. 最后，使用finishTransaction:方法完成交易。當payment的對象被添加到支付隊列

12、中的時候， 會創(chuàng)建一個持久保存的transaction對象來存放它。 當支付被處理后，transaction被更新。 程序中將實現(xiàn)一個觀察者（observer）對象來獲取transaction更新的消息。 觀察者應(yīng)該為用戶提供購買的商品，然后將transaction從隊列中移除。下面介紹在購買過程中用到的幾個類：SKPayment要收集支付信息，先要了解一下支付對象。 支付對象包含了商品的標識（identifier）和要購買商品的數(shù)量（quantity）（數(shù)量可選）。你可以把同一個支付對象重復(fù)放入支付隊列，每一次這樣的動作都相當于一次獨立的支付請求。用戶可以在Settings程序中禁用購買的功

13、能。 因此在請求支付之前，程序應(yīng)該首先檢查支付是否可以被處理。 調(diào)用SKPaymentQueue的canMakePayments方法來檢查。SKPaymentQueue支付隊列用以和App Store之間進行通信。 當新的支付對象被添加到隊列中的時候， Store Kit向App Store發(fā)送請求。 Store Kit將會彈出對話框詢問用戶是否確定購買。 完成的交易將會返回給程序的observer對象。SKPaymentTransactiontransaction對象在每次添加新的payment到隊列中的時候被創(chuàng)建。 transaction對象包含了一些屬性，可以讓程序確定當前的交易狀態(tài)。程

14、序可以從支付隊列那里得到一份審核中的交易列表，但更常用的做法還是等待支付隊列告知交易狀態(tài)的更新。SKPaymentTransactionObserver在程序中實現(xiàn)SKPaymentTransactionObserver的協(xié)議，然后把它作為SKPaymentQueue對象的觀察者。該觀察者的主要職責是：檢查完成的交易，交付購買的內(nèi)容，和把完成后的交易對象從隊列中移除。在程序一啟動，就應(yīng)該為支付隊列指定對應(yīng)的觀察者對象，而不是等到用戶想要購買商品的時候。 Transaction對象在程序退出時不會丟失。程序重啟時， Store Kit繼續(xù)執(zhí)行未完成的交易。 在程序初始化的時候添加觀察者對象，可以

15、保證所有的交易都被程序接收（也就時說，如果有未完成的transaction，如果程序重啟，就重新開始了，如果稍候再添加觀察者，就可能會漏掉部分交易的信息）。恢復(fù)交易信息（Transactions）當transaction被處理并從隊列移除之后，正常情況下，程序就再也看不到它們了。 如果你的程序提供的是非消耗性的或是訂閱類的商品，就必須提供restore的功能，使用戶可以在其他設(shè)備上重新存儲購買信息。Store Kit提供內(nèi)建的功能來重新存儲非消耗商品的交易信息。 調(diào)用SKPaymentQueue的restoreCompletedTransactions的方法來重新存儲。對于那些之前已經(jīng)完成交易

16、的非消耗性商品，Apple Store生成新的，用于恢復(fù)的交易信息。 它包含了原始的交易信息。你的程序可以拿到這個信息，然后繼續(xù)為購買的功能解鎖。 當之前所有的交易都被恢復(fù)時， 就會調(diào)用觀察者對象的paymentQueueRestoreCompletedTransactionsFinished方法。如果用戶試圖購買已經(jīng)買過的非消耗性商品，程序會收到一個常規(guī)的交易信息，而不是恢復(fù)的交易信息。但是用戶不會被再次收費。程序 應(yīng)把這類交易和原始的交易同等對待。訂閱類服務(wù)和消耗類商品不會被Store Kit自動恢復(fù)。 要恢復(fù)這些商品，你必須在用戶購買這些商品時，在你自己的服務(wù)器上記錄這些交易信息， 并且

17、為用戶的設(shè)備提供恢復(fù)交易信息的機制。在程序中添加Store功能本章為添加購買功能的指導(dǎo)詳細流程：準備工作當然是添加StoreKit.framework了。然后是具體的步驟：1. 決定在程序內(nèi)出售的商品的類型。之前提到過，程序內(nèi)可以出售的新feature類型是有限制的。 Store Kit不允許我們下載新的代碼。 你的商品要么可以通過當前的代碼工作（bundle類型），要么可以通過服務(wù)器下載（當然，這里下載的為數(shù)據(jù)文件，代碼是不可以的）。 如果要修改源代碼，就只能老實的升級了。2. 通過iTunes Connect注冊商品每次添加新商品的時候都需要執(zhí)行這一步驟。 每個商品都需要一個唯一的商品標識

18、。 App Store通過這個標識來查找商品信息并處理支付流程。 注冊商品標識的方法和注冊程序的方法類似。要了解如何創(chuàng)建和注冊商品信息，請參考“iTunes Connect Developer Guide”文檔。3. 檢測是否可以進行支付用戶可以禁用在程序內(nèi)部支付的功能。在發(fā)送支付請求之前，程序應(yīng)該檢查該功能是否被開啟。程序可在顯示商店界面之前就檢查該設(shè)置（沒啟用就不顯示商店界面了），也可以在用戶發(fā)送支付請求前再檢查，這樣用戶就可以看到可購買的商品列表了。例子：if(SKPaymentQueue canMakePayments)./Display a store to the userelse

19、./Warn the user that purchases are disabled.4. 獲得商品的信息程序創(chuàng)建SKProductsRequest對象，用想要出售的商品的標識來初始化， 然后附加上對應(yīng)的委托對象。 該請求的響應(yīng)包含了可用商品的本地化信息。/這里發(fā)送請求- (void)requestProductDataSKProductsRequest *request = SKProductsRequest allocinitWithProductIdentifiers:NSSet setWithObject: kMyFeatureIdentifier;request.delegate

20、= self;request start;/這個是響應(yīng)的delegate方法- (void)productsRequest: (SKProductsRequest *)requestdidReceiveResponse: (SKProductsResponse *)responseNSArray *myProduct = ducts;/生成商店的UIrequest autorelease;5. 添加一個展示商品的界面Store Kit不提供界面的類。 這個界面需要我們自己來設(shè)計并實現(xiàn)。6. 為支付隊列（payment queue）注冊一個觀察者對象你的程序需要初始化一個

21、transaction observer對象并把它指定為payment queue的觀察者。上代碼：MyStoreObserver *observer = MyStoreObserver allocinit;SKPaymentQueue defaultQueueaddTransactionObserver: observer;應(yīng)該在程序啟動的時候就添加好觀察者，原因前面說過，重啟后程序會繼續(xù)上次未完的交易，這時就添加觀察者對象就不會漏掉之前的交易信息。7. 在MyStoreObserver類中執(zhí)行paymentQueue: updatedTransactions: 方法。這個方法會在有新的交易

22、被創(chuàng)建，或者交易被更新的時候被調(diào)用。- (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;上面的函數(shù)針對不同的交易返回狀態(tài)，調(diào)用對應(yīng)的處理函數(shù)。8. 觀察者對象在用戶成功購買一件商品時，提供相應(yīng)的內(nèi)容，以下是在交易成功后調(diào)用的方法- (void) completeTransaction: (SKPaymentTransaction *)transaction/你的程序需要實現(xiàn)這兩個方

24、法self recordTransaction: transaction;self provideContent: ductIdentifier;/將完成后的交易信息移出隊列SKPaymentQueue defaultQueuefinishTransaction: transaction;交易成功的信息包含transactionIdentifier和transactionReceipt的屬性。其中，transactionReceipt記錄了支付的詳細信息，這個信息可以幫助你跟蹤、審(我們的)查交易，如果你的程序是用服務(wù)器來交付內(nèi)容，transact

25、ionReceipt可以被傳送到服務(wù)器，然后通過App Store驗證交易。（之前提到的server模式，可以參考以前的圖）9. 如果交易是恢復(fù)過來的（restore），我們用這個方法來處理：- (void) restoreTransaction: (SKPaymentTransaction *)transactionself recordTransaction: transaction;self provideContent: ductIdentifier;SKPaymentQueue defaultQueue finishTransaction

26、: transaction;這個過程完成購買的過程類似。 恢復(fù)的購買內(nèi)容提供一個新的交易信息，這個信息包含了新的transaction的標識和receipt數(shù)據(jù)。 如果需要的話，你可以把這些信息單獨保存下來，供追溯審(我們的)查之用。但更多的情況下，在交易完成時，你可能需要覆蓋原始的transaction數(shù)據(jù)，并使用其中的商品標識。10. 交易過程失敗的話，我們調(diào)用如下的方法：- (void)failedTransaction: (SKPaymentTransaction *)transactionif(transaction.error.code != SKErrorPaymentCance

27、lled)/在這類顯示除用戶取消之外的錯誤信息SKPaymentQueue defaultQueue finishTransaction: transaction;通常情況下，交易失敗的原因是取消購買商品的流程。 程序可以從error中讀出交易失敗的詳細信息。顯示錯誤信息不是必須的，但在上面的處理方法中，需要將失敗的交易從支付隊列中移除。 一般來說，我們用一個對話框來顯示錯誤信息，這時就應(yīng)避免將用戶取消購買這個error顯示出來。11. 組織好程序內(nèi)“商店”的UI。當用戶選擇一件商品時， 創(chuàng)建一個支付對象，并放到隊列中。SKPayment *payment = SKPayment paymen

28、tWithProductIdentifier: kMyFeatureIdentifier;SKPaymentQueue defaultQueue addPayment: payment;如果你的商店支持選擇同一件商品的數(shù)量，你可以設(shè)置支付對象的quantity屬性SKMutablePayment *payment = SKMutablePayment paymentWithProductIdentifier: kMyFeatureIdentifier;payment.quantity = 3;SKPaymentQueue defaultQueue addPayment: payment;下一步

29、：本章中所示代碼可用于內(nèi)置型商品模式(Built-in)。 如果你的程序要使用服務(wù)器來發(fā)布商品，你需要負責設(shè)計和執(zhí)行iPhone程序和你的服務(wù)器之間的通信。服務(wù)器應(yīng)該驗證數(shù)據(jù)并為程序提供內(nèi)容。驗證store的收據(jù)使用服務(wù)器來交付內(nèi)容，我們還需要做些額外的工作來驗證從Store Kit發(fā)送的收據(jù)信息。重要信息：來自Store的收據(jù)信息的格式是專用的。 你的程序不應(yīng)直接解析這類數(shù)據(jù)?？墒褂萌缦碌臋C制來取出其中的信息。驗證App Store返回的收據(jù)信息當交易完成時，Store Kit告知payment observer這個消息，并返回完成的transaction。 SKPaymentTransac

30、tion的transactionReceipt屬性就包含了一個經(jīng)過簽名的收據(jù)信息，其中記錄了交易的關(guān)鍵信息。你的服務(wù)器要負責提交收據(jù)信息來確定其有效性，并保證它未經(jīng)過篡改。 這個過程中，信息被以JSON數(shù)據(jù)格式發(fā)送給App Store，App Store也以JSON的格式返回數(shù)據(jù)。（大家可以先了解一下JSON的格式）驗證收據(jù)的過程：1. 從transaction的transactionReceipt屬性中得到收據(jù)的數(shù)據(jù)，并以base64方式編碼。2. 創(chuàng)建JSON對象，字典格式，單鍵值對，鍵名為receipt-data， 值為上一步編碼后的數(shù)據(jù)。效果為:receipt-data: (編碼后的數(shù)

31、據(jù))3. 發(fā)送HTTP POST的請求，將數(shù)據(jù)發(fā)送到App Store，其地址為:4. App Store的返回值也是一個JSON格式的對象，包含兩個鍵值對， status和receipt:status: 0,receipt: 如果status的值為0， 就說明該receipt為有效的。 否則就是無效的。App Store的收據(jù)發(fā)送給App Store的收據(jù)數(shù)據(jù)是通過對transaction中對應(yīng)的信息編碼而創(chuàng)建的。 當App Store驗證收據(jù)時， 將從其中解碼出數(shù)據(jù)，并以receipt的鍵返回。 返回的響應(yīng)信息是JSON格式，被包含在SKPaymentTransaction的對象中（tra

32、nsactionReceipt屬性）。Server可通過這些值來了解交易的詳細信息。 Apple建議只發(fā)送receipt數(shù)據(jù)到服務(wù)器并使用receipt數(shù)據(jù)驗證和獲得交易詳情。 因為App Store可驗證收據(jù)信息，返回信息，保證信息不被篡改，這種方式比同時提交receipt和transaction的數(shù)據(jù)要安全。（這段得再看看）表5-1為交易信息的所有鍵，很多的鍵都對應(yīng)SKPaymentTransaction的屬性。備注：一些鍵取決于你的程序是鏈接到App Store還是測試用的Sandbox環(huán)境。更多關(guān)于sandbox的信息，請查看Testing a Store一章。Table 5-1 購買信息的鍵：鍵名描述quantity 購買商品的數(shù)量。對應(yīng)SKPayment對象中的quantity屬性product_id商品的標識，對應(yīng)SKPayment對象的productIdentifier屬性。transaction_id交易的標識，對應(yīng)SKPaym