> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# PlayFab Economy 旧版、Unity IAP、Android 入门
> 将 Unity IAP 和 Android Billing API 连接到 PlayFab 旧版 Economy 目录物品，在 Android 设备上实现完整的应用内购买流程。
# PlayFab（旧版 Economy）、Unity IAP 和 Android 入门
Economy v1 API 处于维护模式，不会接收任何新功能，只有 bug 修复。\*\*v1 API 在可预见的将来将持续维护。\*\*参见 [Economy v2 概览](/services/playfab/economy-monetization/economy-v2/overview)，了解有关 PlayFab Economy 下一版本的更多信息！
本教程向你展示如何使用 PlayFab、Unity + IAP 服务和 Android Billing API 设置应用内购买 (IAP)。
## 开始之前
设置 IAP 可能很繁琐，尤其是当你不确定不同的服务应如何集成和协作时。
下图展示了 Android Billing API 和 PlayFab 如何协同工作，为你的客户端提供稳定的 IAP 体验。
首先通过 PlayMarket 设置你的 **Product IDs** 和 **Prices**。最初，所有产品都是*无标识的*——它们是玩家能够购买的数字实体——但对于 PlayFab 玩家来说没有意义。
为了让这些实体有用，我们需要在 PlayFab 物品目录中镜像它们。这会把无标识的实体变成捆绑包、容器和单个物品。
每个都有自己独特的标识，包括：
* **Titles**
* **Descriptions**
* **Tags**
* **Types**
* **Images**
* **Behaviors**
所有这些通过共享 ID 与市场产品关联。
访问可购买的真实货币物品的最佳方式是使用 [GetCatalogItems](xref:titleid.playfabapi.com.client.title-widedatamanagement.getcatalogitems) 和 [GetStoreItems](xref:titleid.playfabapi.com.client.title-widedatamanagement.getstoreitems)。这些与免费货币商店使用的 API 方法相同，所以该过程应该很熟悉。
物品的 ID 是 PlayFab 与任何外部 IAP 系统之间的链接。因此我们将物品 ID 传递给 IAP 服务。
此时，购买过程开始。玩家与 IAP 界面交互——如果购买成功，你将获得一个收据。
然后 PlayFab 能够验证收据并登记购买，将玩家刚刚购买的物品授予 PlayFab 玩家。
这是 IAP 集成如何工作的大致思路，以下示例展示了大部分实际操作。
## 设置客户端应用程序
本节向你展示如何配置一个非常初级的应用程序，使用 PlayFab、UnityIAP 和 Android Billing API 测试 IAP。
先决条件：
* 一个 Unity 项目。
* 已导入并配置为可与你的游戏协同工作的 PlayFab SDK。
我们的第一步是设置 UnityIAP：
1. 导航到 **Services**。
2. 确保选中 **Services** 选项卡。
3. 选择你的 **Unity Services** 配置文件或组织。
4. 选择 **Create** 按钮。
1. 接下来，导航到 **In-App Purchasing (IAP)** 服务。
1. 通过设置 **Simplify cross-platform IAP** 开关，确保启用**服务**。
2. 然后选择 **Continue** 按钮。
将出现一个包含插件列表的页面。
1. 选择 **Import** 按钮。
继续执行 Unity 安装和导入过程，直到导入所有插件。
1. 验证插件已就绪。
2. 然后创建一个名为 **AndroidIAPExample.cs** 的新脚本。
`AndroidIAPExample.cs` 将包含以下所示的代码（请参阅代码注释以获得进一步的解释）。
```csharp theme={null}
using PlayFab;
using PlayFab.ClientModels;
using PlayFab.Json;
using System;
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.Purchasing;
public class AndroidIAPExample : MonoBehaviour, IStoreListener {
// Items list, configurable via inspector
private List Catalog;
// The Unity Purchasing system
private static IStoreController m_StoreController;
// Bootstrap the whole thing
public void Start() {
// Make PlayFab log in
Login();
}
public void OnGUI() {
// This line just scales the UI up for high-res devices
// Comment it out if you find the UI too large.
GUI.matrix = Matrix4x4.TRS(new Vector3(0, 0, 0), Quaternion.identity, new Vector3(3, 3, 3));
// if we are not initialized, only draw a message
if (!IsInitialized) {
GUILayout.Label("Initializing IAP and logging in...");
return;
}
// Draw menu to purchase items
foreach (var item in Catalog) {
if (GUILayout.Button("Buy " + item.DisplayName)) {
// On button click buy a product
BuyProductID(item.ItemId);
}
}
}
// This is invoked manually on Start to initiate login ops
private void Login() {
// Login with Android ID
PlayFabClientAPI.LoginWithAndroidDeviceID(new LoginWithAndroidDeviceIDRequest() {
CreateAccount = true,
AndroidDeviceId = SystemInfo.deviceUniqueIdentifier
}, result => {
Debug.Log("Logged in");
// Refresh available items
RefreshIAPItems();
}, error => Debug.LogError(error.GenerateErrorReport()));
}
private void RefreshIAPItems() {
PlayFabClientAPI.GetCatalogItems(new GetCatalogItemsRequest(), result => {
Catalog = result.Catalog;
// Make UnityIAP initialize
InitializePurchasing();
}, error => Debug.LogError(error.GenerateErrorReport()));
}
// This is invoked manually on Start to initialize UnityIAP
public void InitializePurchasing() {
// If IAP is already initialized, return gently
if (IsInitialized) return;
// Create a builder for IAP service
var builder = ConfigurationBuilder.Instance(StandardPurchasingModule.Instance(AppStore.GooglePlay));
// Register each item from the catalog
foreach (var item in Catalog) {
builder.AddProduct(item.ItemId, ProductType.Consumable);
}
// Trigger IAP service initialization
UnityPurchasing.Initialize(this, builder);
}
// We are initialized when StoreController and Extensions are set and we are logged in
public bool IsInitialized {
get {
return m_StoreController != null && Catalog != null;
}
}
// This is automatically invoked automatically when IAP service is initialized
public void OnInitialized(IStoreController controller, IExtensionProvider extensions) {
m_StoreController = controller;
}
// This is automatically invoked automatically when IAP service failed to initialized
public void OnInitializeFailed(InitializationFailureReason error) {
Debug.Log("OnInitializeFailed InitializationFailureReason:" + error);
}
// This is automatically invoked automatically when purchase failed
public void OnPurchaseFailed(Product product, PurchaseFailureReason failureReason) {
Debug.Log(string.Format("OnPurchaseFailed: FAIL. Product: '{0}', PurchaseFailureReason: {1}", product.definition.storeSpecificId, failureReason));
}
// This is invoked automatically when successful purchase is ready to be processed
public PurchaseProcessingResult ProcessPurchase(PurchaseEventArgs e) {
// NOTE: this code does not account for purchases that were pending and are
// delivered on application start.
// Production code should account for such case:
// More: https://docs.unity3d.com/ScriptReference/Purchasing.PurchaseProcessingResult.Pending.html
if (!IsInitialized) {
return PurchaseProcessingResult.Complete;
}
// Test edge case where product is unknown
if (e.purchasedProduct == null) {
Debug.LogWarning("Attempted to process purchase with unknown product. Ignoring");
return PurchaseProcessingResult.Complete;
}
// Test edge case where purchase has no receipt
if (string.IsNullOrEmpty(e.purchasedProduct.receipt)) {
Debug.LogWarning("Attempted to process purchase with no receipt: ignoring");
return PurchaseProcessingResult.Complete;
}
Debug.Log("Processing transaction: " + e.purchasedProduct.transactionID);
// Deserialize receipt
var googleReceipt = GooglePurchase.FromJson(e.purchasedProduct.receipt);
// Invoke receipt validation
// This will not only validate a receipt, but will also grant player corresponding items
// only if receipt is valid.
PlayFabClientAPI.ValidateGooglePlayPurchase(new ValidateGooglePlayPurchaseRequest() {
// Pass in currency code in ISO format
CurrencyCode = e.purchasedProduct.metadata.isoCurrencyCode,
// Convert and set Purchase price
PurchasePrice = (uint)(e.purchasedProduct.metadata.localizedPrice * 100),
// Pass in the receipt
ReceiptJson = googleReceipt.PayloadData.json,
// Pass in the signature
Signature = googleReceipt.PayloadData.signature
}, result => Debug.Log("Validation successful!"),
error => Debug.Log("Validation failed: " + error.GenerateErrorReport())
);
return PurchaseProcessingResult.Complete;
}
// This is invoked manually to initiate purchase
void BuyProductID(string productId) {
// If IAP service has not been initialized, fail hard
if (!IsInitialized) throw new Exception("IAP Service is not initialized!");
// Pass in the product id to initiate purchase
m_StoreController.InitiatePurchase(productId);
}
}
// The following classes are used to deserialize JSON results provided by IAP Service
// Please, note that JSON fields are case-sensitive and should remain fields to support Unity Deserialization via JsonUtilities
public class JsonData {
// JSON Fields, ! Case-sensitive
public string orderId;
public string packageName;
public string productId;
public long purchaseTime;
public int purchaseState;
public string purchaseToken;
}
public class PayloadData {
public JsonData JsonData;
// JSON Fields, ! Case-sensitive
public string signature;
public string json;
public static PayloadData FromJson(string json) {
var payload = JsonUtility.FromJson(json);
payload.JsonData = JsonUtility.FromJson(payload.json);
return payload;
}
}
public class GooglePurchase {
public PayloadData PayloadData;
// JSON Fields, ! Case-sensitive
public string Store;
public string TransactionID;
public string Payload;
public static GooglePurchase FromJson(string json) {
var purchase = JsonUtility.FromJson(json);
purchase.PayloadData = PayloadData.FromJson(purchase.Payload);
return purchase;
}
}
```
1. 创建一个名为 **Code** 的新 **Game** 对象。
2. 向其添加 `AndroidIAPExample` 组件（2 步过程）。
3. 向其添加 `AndroidIAPExample` 组件。
4. 确保**保存**场景。
最后，导航到 **Build Settings**。
1. 验证你的场景已添加到 **Scenes In Build** 区域。
2. 确保已选择 **Android** 平台。
3. 移动到 **Player Settings** 区域。
4. 分配你的 **Package Name**。
确保设定你*自己的*包名以避免任何 **PlayMarket** 冲突。
最后，像往常一样构建应用程序，确保你安全地拥有一个 APK。
我们暂时还无法测试它。我们需要先配置 PlayMarket 和 PlayFab，这在以下部分中描述。
## 为 IAP 设置 PlayMarket 应用程序
本节介绍如何为你的 PlayMarket 应用程序启用 IAP 的具体细节。
设置应用程序本身超出了本教程的范围。我们假设你已经*拥有*一个应用程序，并且已配置为至少发布 Alpha 版本。
有用的注意事项：
* 达到该点将需要你上传一个 APK。请使用我们在上一节中构建的 APK。
* 当要求你上传 APK 时，你可以将其作为 Alpha 或 Beta 应用程序上传，以启用 IAP 沙盒。
* 配置 **Content Rating** 将包括有关如何在应用程序中启用 IAP 的问题。
* PlayMarket *不*允许发布者使用或测试 IAP——所以请为测试目的选择*另一个* Google 帐户，并将其添加为你的 Alpha/Beta 版本的测试者。
一旦你发布了应用程序版本：
1. 从菜单中选择 **In-app products**。
* 如果要求你提供 **Merchant Account**，请关联或创建一个。
2. 选择 **Add New Product** 按钮。
1. 在下面显示的此屏幕上，选择 **Managed Product**。
2. 给它一个描述性的 **Product ID**。
3. 选择 **Continue**。
PlayMarket 要求你填写 **Title (1)** 和 **Description (2)**。但是，在我们的情况下，这些用处不大。
我们将只从 PlayFab 服务获取 **Data Item** 数据，只需要 ID 匹配。
1. 进一步滚动并选择 **Add a price** 按钮。
1. 输入一个有效价格（注意每个国家/地区如何单独换算价格）。
2. 选择 **Apply** 按钮。
1. 最后，滚动回屏幕顶部，将物品的状态更改为 **Active**。
虽然这已经完成了应用程序的配置，但我们还需要进行几处调整。首先，让我们保存 **Licensing Key**（这将方便将 PlayFab 与 PlayMarket 关联）。
1. 在菜单中导航到 **Services & APIs**。
2. 然后找到并保存 **Key** 的 **Base64** 版本。
下一步是启用 IAP 测试。虽然沙盒会自动为 Alpha 和 Beta 版本启用，但我们需要设置经授权测试应用程序的帐户：
1. 导航到 **Home**。
2. 在左侧菜单中找到并选择 **Account details**。
3. 找到 **License Testing** 区域。
4. 验证你的 **Test Accounts** 在列表中。
5. 确保 **License Test Response** 设置为 **RESPOND\_NORMALLY**。
不要忘记应用设置！
此时应完成集成的 Play Market 端设置。
## 设置 PlayFab 游戏
我们的最后一步是配置 PlayFab 游戏以反映我们的产品，并与 Google Billing API 集成。
1. 选择 **Add-ons**。
2. 然后，选择 **Google** 附加组件。
1. 填写你的 **Package ID**。
2. 填写你在上一节中获取的 **Google App License Key**。
3. 通过选择 **Install Google** 按钮提交更改。
我们的下一步是在 PlayFab 中反映我们的 Golden Sword 物品：
1. 选择 **Economy**。
2. 验证已选中 **Catalogs** 子选项卡。
3. 选择 **New Catalog**。
4. 提供一个 **Catalog version** 名称。
5. 选择 **Save Catalog**。
如果目录没有物品，它将*自动*被移除。这就是为什么任何新目录都会预先添加一个名为 **One** 的物品。
我们*始终*可以创建一个*新*物品，但为了保持整洁，让我们修改现有的 **One** 物品。
1. 选择该物品以编辑 **Item ID**，使其与 PlayMarket 中的 ID 匹配。
2. 现在，编辑 **Display name** 并添加 **Description**。
请记住，此数据与 **Play Market Item Title** 和 **Description** *毫无关系*——它*完全*独立。
1. 为你的 **Item** 分配一个 **Price**。
2. 选择 **Save Item** 以提交更改。
在本教程中，IAP 主要指用真实货币的购买。这就是为什么我们使用 **RM** - 特殊的真实货币。PlayFab 金额以美分定义。
1. 观察 **Item ID** 列表中的物品。
至此完成了 PlayFab 游戏的设置。
## 测试
出于测试目的，使用 Alpha/Beta 版本下载应用程序。
* 确保使用测试帐户和真实的 Android 设备。
* 一旦启动应用程序，你应该会看到 IAP 已初始化，并且*一个按钮*代表你的物品。
* 选择该按钮。
IAP 购买将被发起。按照 Google Play 说明操作，直到购买成功。
最后，导航到 PlayFab **Game Manager** 仪表板中的你的游戏，找到 **New Events**。
这意味着购买已成功提供、验证并传输到 PlayFab 生态系统。
至此，你已成功地将 UnityIAP 和 Android Billing API 集成到你的 PlayFab 应用程序中。
## Related topics
- [使用 Economy v2、Unity IAP 和 Android 快速入门](/zh-CN/services/playfab/economy-monetization/economy-v2/tutorials/getting-started-with-unity-and-android.md)
- [物品（旧版 Economy）](/zh-CN/services/playfab/economy-monetization/economy/items/index.md)
- [Multiplayer Android 入门](/zh-CN/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/android-specific-requirements.md)
- [Economy（旧版）快速入门](/zh-CN/services/playfab/economy-monetization/economy/quickstart.md)
- [PlayFab Economy v2 文档](/zh-CN/services/playfab/economy-monetization/index.md)