Skip to main content

​
Requirements

  • Playtolia SDK (with Authentication and Billing enabled)

​
Store API

Playtolia Store API allows you to list, query, and search store items. Store API supports different types of items such as NonConsumable, Consumable, and Subscription. Store API also provides a simple function to start the purchase flow for any item in your store. Store API works with Play Store and App Store APIs in order to securely process payments, grant items to your players, and handle failures.
Store data is only available after successful authentication. PlaytoliaStore functions will return empty lists or null values until the player is logged in.

​
Getting all available items

Import the PlaytoliaSDK.Runtime to your script by adding the using directive
StoreController.cs
using PlaytoliaSDK.Runtime;
Call the GetItems function to retrieve all available store items
StoreController.cs
// Get all items
var allItems = PlaytoliaStore.GetItems();
Once you authenticate your user, PlaytoliaStore will automatically refresh and fetch the latest available items. If you need to refresh the store items manually, simply use PlaytoliaStore.Refresh() function.

​
Understanding StoreItem structure

Each StoreItem contains comprehensive information about purchasable content:
  • Id: Unique identifier for the store item
  • Name: Display name for the item
  • Sku: Platform-specific product identifier (App Store/Google Play)
  • Type: Item type (consumable, non-consumable, subscription)
  • Grants: Array of grants this item provides when purchased
StoreItemDisplay.cs
public void DisplayStoreItemInfo(StoreItem item)
{
    Debug.Log($"Store Item ID: {item.Id}");
    Debug.Log($"Name: {item.Name}");
    Debug.Log($"SKU: {item.Sku}");
    Debug.Log($"Type: {item.Type}");
    Debug.Log($"Number of grants: {item.Grants.Length}");

    // Display each grant
    foreach (var grant in item.Grants)
    {
        Debug.Log($"Grant ID: {grant.GrantId}");
        Debug.Log($"Grant Type: {grant.GrantType}");
        Debug.Log($"Grant Amount: {grant.GrantAmount}");
        if (grant.Currency != null)
        {
            Debug.Log($"Currency: {grant.Currency.Name}");
        }
    }
}

​
Searching and filtering items

Call the SearchItems function to search items by their name, description, or SKU
StoreController.cs
// Search for items with "Gold" in their name, description, or sku
var searchResult = PlaytoliaStore.SearchItems("Gold");

// Get items by type
var consumables = PlaytoliaStore.GetItemsByType("Consumable");
var subscriptions = PlaytoliaStore.GetItemsByType("NonConsumable");
var nonConsumables = PlaytoliaStore.GetItemsByType("Subscription");

​
Getting specific items

PlaytoliaStore includes two getter functions to help you get a specific StoreItem by item ID or SKU
StoreController.cs
// Get an item by ID
var itemById = PlaytoliaStore.GetItemById("gold_500");

// Get an item by SKU
var itemBySku = PlaytoliaStore.GetItemBySku("com.mygame.coinpack_500");

​
Making a purchase

When your player is ready to purchase an item, simply use the BeginPurchaseFlow function and pass a StoreItem
StoreController.cs
StoreItem item = PlaytoliaStore.GetItemBySku("com.mygame.coinpack_500");
PlaytoliaStore.BeginPurchaseFlow(item);

// Or purchase by item ID
PlaytoliaStore.BeginPurchaseFlow("gold_500");

​
Understanding the purchase flow

Purchase flows are a composition of several requests:
  1. Client validation: Calls to App Store or Google Play Store to ensure billing is available, fetch the item, and display the IAP dialog
  2. Server verification: A verification call to Playtolia servers to check purchase integrity and update user wallets, subscriptions, and entitlements
  3. Purchase acknowledgment: A final call to the billing clients to acknowledge (or consume) the purchase
The SDK makes all necessary requests and calls with a single BeginPurchaseFlow function. Most of the process is handled in different threads in an asynchronous manner, in order to prevent your game from lagging or freezing. EventBus component offers a fast, non-blocking, and safe way to consume results of async flows by storing and passing references of local callback objects named EventHandles.

​
Using EventBus to handle IAP results

Simply create an EventHandle with your success and error callbacks
PurchaseHandler.cs
using PlaytoliaSDK.Runtime;
using PlaytoliaSDK.Runtime.Common;
using UnityEngine;

public class PurchaseHandler : MonoBehaviour
{
    public void HandlePurchase(StoreItem item)
    {
        var onSuccess = (Packet p) => {
            ShowPurchaseSuccessfulDialog(item);
        };

        var onError = (Packet p) => {
            SDKResult r = (SDKResult) p.Data;
            var message = r.Message;
            Debug.Log("Purchase failed: " + message);
            ShowPurchaseErrorDialog(message);
        };

        var handle = EventBus.Register(onSuccess, onError);

        // Start purchase with event handle
        PlaytoliaStore.BeginPurchaseFlow(item, handle);
    }

    void ShowPurchaseSuccessfulDialog(StoreItem item)
    {
        Debug.Log($"Purchase successful: {item.Name}");
        // Show success UI with item rewards
        DisplayItemRewards(item);
    }

    void ShowPurchaseErrorDialog(string errorMessage)
    {
        Debug.Log($"Purchase failed: {errorMessage}");
        // Show error dialog to user
    }

    void DisplayItemRewards(StoreItem item)
    {
        foreach (var grant in item.Grants)
        {
            if (grant.Currency != null)
            {
                Debug.Log($"Received {grant.GrantAmount} {grant.Currency.Name}");
            }
            else
            {
                Debug.Log($"Received {grant.GrantId}");
            }
        }
    }
}

​
Understanding Grant structure

Each Grant represents a reward that will be given to the player upon purchase:
  • Id: Unique identifier for the grant
  • GrantId: The identifier used to group similar grants
  • GrantType: Type of grant (currency, entitlement, etc.)
  • GrantAmount: Amount to be granted
  • Currency: Currency object (if this grant gives currency)
GrantAnalyzer.cs
public void AnalyzeGrants(StoreItem item)
{
    Debug.Log($"Analyzing grants for {item.Name}:");

    foreach (var grant in item.Grants)
    {
        Debug.Log($"Grant ID: {grant.Id}");
        Debug.Log($"Grant Type: {grant.GrantType}");
        Debug.Log($"Grant Amount: {grant.GrantAmount}");

        if (grant.Currency != null)
        {
            Debug.Log($"Currency Grant: {grant.GrantAmount} {grant.Currency.Name}");
        }
        else
        {
            Debug.Log($"Non-currency Grant: {grant.GrantId}");
        }
    }
}

​
Listen to store changes

Store items can change during runtime due to:
  • Server updates: New items added or existing items modified
  • A/B testing: Different item configurations for different users
  • Regional changes: Items available in different regions
  • Manual refresh via PlaytoliaStore.Refresh()
StoreMonitor.cs
public void Start()
{
    PlaytoliaStore.AddListener(() => {
        var items = PlaytoliaStore.GetItems();
        Debug.Log($"Store updated with {items.Count} items");
    });
}

​
Need to track purchases and balances?

Use the Wallet and Entitlements APIs to monitor what players receive from their purchases.

Wallets

Manage virtual currencies and player balances using PlaytoliaWallet

Entitlements

Manage player entitlements and subscriptions using PlaytoliaEntitlements