在Unity中使用ONE store In-App支付
Last updated
Last updated
ONE store支付插件在Unity環境拓展asset,提供在遊戲中one store支付程序庫的最新功能。本指南對設置project使用插件的方法,以及展現ONE store支付程序庫功能的方法進行說明。
可以在GitHub的 Release 頁面下載Unity用ONE store app内支付插件的最新版本。
在Unity選單欄點擊Assets > Import Package > Custom Package
找到下載位置選擇.unitypackage文件。
Import Unity Package對話框内所有Assets都選上,點擊Import。
導入Package生成新文件夾。這個文件夾裡包括ONE store支付程序庫。
Assets/OneStoreCorpPlugins
/Common
/Authentication
/Purchase
/AppLicenseChecker
EDM4U(External Dependency Manager for Unity)必須一起發行。 如果已經在使用,在Import Package階段解除檢測ExternalDependencyManager適用即可。
要在Project包含倉庫及從屬性,需要遵循如下階段。
Project Settings > Player > Publishing Settings > Build
檢測以下兩方面
Custom Main Manifest
選擇 Assets > External Dependency Manager > Android Resolver > Force Resolve
可以在mainTemplete.gradle
文件確認適用如下内容。
In-app Purchase從屬性列出如下。 Assets/OneStoreCorpPlugins/Purchase/Editor/PurchaseDependencies.xml
App License Checker 從屬性列出如下。 Assets/OneStoreCorpPlugins/AppLicenseChecker/Editor/AppLicenseCheckerDependencies.xml
需要在AndroidManifest.xml
文件設置。詳細内容請參考公告事項。
如果不設置<queries>,就无=無法在SDK找到ONE store服務。.
是強制SDK和全球store聯動的選項。本功能從SDK v21.01.00版本開始適用。
發行组建版本中,本選項必須刪除。
在研發階段設置Log level,可以更仔细顯示SDK的數據流向。以android.util.Log内定義的值為基礎運作。
VERBOSE
2
DEBUG
3
INFO (default)
4
WARN
5
ERROR
6
發行组建版本網絡安全比較弱,本選項需要刪除。
為了請求app内支付,需要使用ONE store研發者中心提供的許可證密鑰對PurchaseClientImpl
對象進行初始化。調用Initialize()
函數完成基本配置。這是為了連接ONE store服務的先行操作。
PurchaseClientImpl
對象初始化结束後,如果通過QueryProductDetails()
請求商品資訊,以IPurchaseCallback.OnProductDetailsSucceeded()
接收回覆。
ProductType
如下
管理型商品
ProductType.INAPP
定期支付商品 (訂閱商品)
ProductType.SUBS
包月型商品
(該商品今後本商品將不予支持) ProductType.AUTO
想一次性查詢上述所有類型資訊,請設置ProductType.ALL
。
ProductType.ALL
僅可在查詢商品詳細資訊中使用,在請求購買,查詢購買明細中無法使用。
應用程序內商品ID列表要在研發者的網或安全後端伺服器上管理。
為了在app請求購買,要在基本線程調用Purchase()
函數。
以調用QueryProductDetails()
API獲取的ProductDetail
對象的值為基礎,生成PurchaseFlowParams
對象。
要生成PurchaseFlowParams
對象,需要使用PurchaseFlowParams.Builder
class。
SetDeveloperPayload()
作为研發者任意輸入的值,最多為200byte。此值可以用於確認支付後資訊的整合性和附加資訊。
SetProductName()
在支付時想要更改顯示商品名的情况下使用。
SetQuantity()
僅用於管理型app内商品,在購買數個同一商品时使用。
ONEstore正在進行為用戶提供優惠券、現金卡等諸多優惠宣傳活動。
研發公司可以在請求購買時使用gameUserId
、 promotionApplicable
參數,限制或允许app用户参与宣传活动。
研發公司傳送app的固有用户識別號碼及選擇是否參加宣傳活動,one store以此值為基礎,適用用戶的宣傳優惠。
gameUserId
, promotionApplicable
參數作為選項值,僅在事先與ONE store事業部負責人協商宣傳活動時使用,其他一般情况下不發送值。
另外,即使達成事先協議並發錯值,為了保護個人資訊,gameUserId也必須以hash的固有值形式傳送。
如果成功調用Purchase()
,顯示如下界面。【圖片1】顯示显示管理型商品支付購買界面。
如果購買成功,向IPurchaseCallback.OnPurchaseSucceeded()
函數傳送结果。
失敗時調用IPurchaseCallback.OnPurchaseFailed()
函數。
如果購買成功, 購買數據還會生成用戶及商品ID的固有識別符號購買token。購買token雖然可以在應用軟件内儲存,但是最好將token傳送到驗證購買、避免詐騙的後端伺服器。
管理型商品和定期支付商品的購買token在每次支付的時候都會發行購買token。(包月型商品自動支付更新期間,購買token將保持不變。)
另外,用戶會通過電子郵件接收包含收據號碼的交易收據。管理型商品每次購買都會接收電子郵件,包月型商品和定期支付商品在第一次購買和之後有更新的時候會接收電子郵件。
定期支付在取消之前一直自動更新。定期支付可能有以下狀態。
激活:用戶使用内容過程中没有問題的良好狀態,可以接觸定期支付。
預约暫停:用戶使用定期支付期間想要暫停時可以選擇。
周定期支付:以1-3周為單位進行暫停。
月定期支付:以1-3個月為單位進行暫停。
年定期支付:不予支持暫停。
預约解除:雖然用戶正在使用定期支付,但想取消時可以選擇。下一個支付日將不會支付。
延期,保留:如果用戶出現支付問題,則無法在下一個支付日支付。用戶不能取消預约,可以立即“解除訂閱”。
用戶想要升级或降级定期支付時,可以在購買時設置比例分配模式,或者設置變更事項影響到定期支付用戶的方式。
下表是可以使用的比例分配模式(OneStoreProrationMode
)
比例分布模式
說明
IMMEDIATE_WITH_TIME_PRORATION
定期支付的變更將立即進行,剩餘時間基於差價調整後退款或支付。(這是基本操作)
IMMEDIATE_AND_CHARGE_PRORATED_PRICE
定期支付的變更將立即進行,請求支付周期和之前一致。請求用戶支付剩餘時間的價格。(本選項僅是在更新中可使用)
IMMEDIATE_WITHOUT_PRORATION
定期支付的變更將立即進行,下一個支付日支付新的價格。請求支付周期和之前一致。
DEFERRED
現有套餐到期後立即變更,同時發给用戶新的資費。
定期支付可以使用與請求購買同一個API,向用戶提供升级或降级。但是,為了適用定期支付的升级與降级,必須具備現有定期支付購買token和比例分配模式值。
如下例子,需要提供現有定期支付、今後(升级或降级)定期支付以及比例分配模式相關資訊。
因為升级或降级也會執行請求購買邏輯,所以接收同樣回覆。
另外,也會在查詢購買明细中有請求時接收回覆。用比例分配模式購買也和一般購買一樣,需要使用PurchaseClientImpl.AcknowledgePurchase()
行購買後處理。
如果用戶購買完成,需要在應用軟件進行購買處理。 大部分情况下,應用軟件通過OnPurchaseSucceeded()
得購買通知。或者如查詢購買明细說明那樣,也有應用軟件調用PurchaseClientImpl.QueryPurchases()
函數處理的情况。
管理型商品在使用之前不能再次購買。
為了使用商品,調用ConsumePurchase()
。另外,使用操作结果調用為IPurchaseCallback..OnConsumeSucceeded()
。
不使用管理型商品時,可以作為永久性形態的商品使用, 購買後立即使用時,也可以作為使用性形態的商品使用。
另外,如果特定時間後使用,還可以作為固定期限形態的商品使用 。
使用請求有時會失敗, 因此必須檢查安全後端伺服器,確認各購買token是否使用。只有這樣應用軟件才不會對同一個購買進行多次授權。或者,在授權之前, 可以等到成功使用回覆為止。
3天内不確認購買(acknowledge)或不使用(consume),判斷為没有為用戶提供商品,自動退款给用戶。
如果驗證非使用型商品,使用PurchaseClientImpl.AcknowledgePurchase()
函數。管理型商品、包月型商品、訂閱型商品均可使用。
使用PurchaseData.Acknowledged()
函數判斷是否已驗證。另外,驗證操作成功後,將調用IPurchaseCallback.OnAcknowledgeSucceeded()
函數。
僅僅處理購買,不足以保證應用軟件處理了所有購買。應用軟件可能無法識別用戶購買的全部商品。 應用軟件可能錯過購買跟踪或無法識別購買等幾種情况如下。
網絡問題:用戶成功購買,ONE store上也收到確認,但是設備在接收購買通知之前,發生網絡連接斷開的情况。
多個設備:用戶在一台設備上購買商品後,切換到其他設備時,期待顯示該商品。
為了處理這種情况,需要在應用軟件的Start()
或OnApplicationPause()
中調用PurchaseClientImpl.QueryPurchases()
,按照購買後處理說明來確認所有購買是否已經成功處理。
包月型商品是最初購買後30天更新的商品。包月型商品的狀態可以通過PurchaseData.RecurringState()
確認。
如果要更改包月型商品的狀態,請使用PurchaseClientImpl.ManageRecurringProduct()
。輸入購買數據和要更改的RecurringAction
值 。
可以示管理訂閱商品狀態的界面。
作為參數輸入PurchaseData
後,確認購買數據,運行相應定期支付商品的管理界面。但是輸入null
時,運行用戶的定期支付列表界面。下面是顯示定期支付管理界面的方法的示例。
從SDK v19版本以上開始,為了使用S2S API需要市場分類代碼。
PurchaseClientImpl
對象初始化時,SDK嘗試與支付模塊連接。此時連接成功就會自動導入StoreCode
。
PurchaseClientImpl.StoreCode
變數有配額。
ONE store服務的版本低或者没有時,無法使用app内支付。首次調用API時,首先嘗試與ONE store服務連接。此時,如果發生RESULT_NEED_UPDATE
,則需要調用LaunchUpdateOrInstallFlow()
方法。
ONE store app内SDK只要用戶登錄ONE store才能啟動。内部首先嘗試以登錄token進行登錄。失敗或最初登錄等没有用戶資訊時,會顯示前台登錄畫面,引導用戶登錄。
Custom Main Gradle Template
Unity
2020.3.48f1
Java SDK (Java 11)
Purchase: v21.01.00
App License Checker: v2.1.0