Skip to main content

PlayFab integration V1

info

Please see the first chapter below for current limitations and restrictions that apply when using PlayFab.

This guide explains how to configure PlayFab services for Simple IAP System, specifically cloud save and receipt validation. Additionally, methods are being explained for keeping local user inventory in sync with PlayFab.

danger

Please note that PlayFab Economy V1 is a legacy integration. V2 integration is currently in beta in a GitHub-only release. V1 will not receive further updates and the screenshots in this guide might not match or be outdated.

Prerequisites

What else can you do to avoid cheating? To put it simple – don’t do everything on the client, but verify each user action on external servers.

The PlayFab 'full' integration in Simple IAP System (not only receipt verification) is a great starting point for that by keeping everything in sync with cloud save and doing critical transactions (like purchasing) on their servers only.

If you're using the full suite of PlayFab in Simple IAP System, this means that no data is saved on the device. As it requires an online connection throughout the whole play session, it is the most secure solution by far, although better suited at devices supporting a reliable internet connection (desktop pc's via ethernet or mobile devices using wi-fi). Please keep that in mind when making use of this. Basically you have two options with online-only games when there is no internet connection available:

  • logging into PlayFab is not possible - it would be best to disallow entering the game at this state
  • or, only permit offline mode without earning & spending (such as a training mode with local scores)

Also note that with the various different native plugins supporting mobile login via PlayFab (i.e. Play Game Services by Google), I am not able to write a separate integration guide for each of them: the default login method is via registered email addresses, or automatic login using Steam and Facebook session tokens (more on this in chapter 6), which are the most common techniques for desktop applications. Please refer to the PlayFab documentation for implementing other login methods.

For clarity, this guide describes two possible implementations of PlayFab:

  • Validation Only: requires an internet connection at the time of processing an in-app purchase
  • Full Suite: default when 'Validation Only' is not checked, requiring an internet connection for all inventory actions

With that out of the way, let's continue by creating your PlayFab developer account.

Creating a PlayFab account

Creating a PlayFab developer account is easy and free. Sign up here: PlayFab Website

Once you're logged in, you will be greeted by a somewhat empty screen, where you can define your company and game name. In PlayFab, when speaking about games, they are usually referred to as 'titles'. Each game must have its own title (or dashboard), which is used to independently track users, purchases, cloud scripts and all the other stuff PlayFab provides.

If you've created your first title, it should be shown under your games page along with its generated title identifier.

PlayFab-Integration010

Creating your store catalog

Now with the title created in PlayFab, we need a way to transfer all the different in-app purchase products from Unity to PlayFab. Fortunately, this is very easy by using the JSON export provided in Simple IAP System, as it already contains the correct format and properties. Open the IAP Project Settings at the Tools tab. Clicking on the 'Export to JSON' button and choosing an export folder will result in the following files being created:

PlayFab-Integration020

  • SimpleIAPSystem_Currencies.json** (currencies with name and default value)
  • SimpleIAPSystem_IAPSettings.json (all IAP products, including free ones)
  • SimpleIAPSystem_IAPSettings_PlayFab.json (all IAP products, excluding free ones)

PlayFab-Integration030

After that, go to the Economy > Catalogs section and upload all of your IAP products as well, by clicking on 'Upload JSON' and selecting the SimpleIAPSystem_IAPSettings_PlayFab.json file. You can then click on your catalog ID and verify that all products and currency bundles are actually there.

PlayFab-Integration040

Make this catalog your primary catalog by clicking on the small settings icon and toggling the 'Primary Catalog' checkbox. You can see that everything is correct when the catalog is showing 'Primary' in its header.

PlayFab-Integration060 PlayFab-Integration070 PlayFab-Integration080

Importing the PlayFab Unity SDK

First of all, download the PlayFab Unity SDK from here: https://api.playfab.com/sdks/unity

You have several download options on this page, but I would recommend downloading the regular 'PlayFab SDK'. The 'Editor Extensions' helper is a nice idea, which didn't work out the last time I've tried it, as it lost connection to PlayFab's server and the title quite often. So if you don't want to update the SDK every week, just go with the regular download.

PlayFab-Integration090

After downloading, import the PlayFab SDK into your Unity project. For establishing the relation between the SDK and your title on PlayFab's servers, you will have to enter its title ID in the SDK settings. Locate the 'PlayFabSharedSettings' file in your project as shown below, then enter the title ID that has been generated for you in PlayFab's dashboard (see first screenshot in this thread).

PlayFab-Integration100 PlayFab-Integration110

Lastly, since the IAPManager needs to be aware that you are now going to use PlayFab features as well, you have to drag and drop our PlayFabManager prefab found under SimpleIAPSystem > Prefabs > Resources in the same scene like the IAPManager. If you don't do this, a temporary instance of the PlayFabManager (along with a warning message) will get instantiated so your app will continue working.

PlayFab-Integration120 PlayFab-Integration130

Using receipt validation only

'Validation Only' means that in-app purchase receipts from your app will get sent to PlayFab for validation and approval, but you are not planning to use any other PlayFab features (cloud save, cloud scripts, analytics, product sales, and so on). In this case, see the PlayFabManager prefab and toggle 'Validation Only'.

The ReceiptValidatorService component should exist on your PlayFabManager prefab, regardless of whether you have enabled 'Validation Only' or not.

PlayFab-Integration140

For verifying real in-app purchase receipts, PlayFab needs some of your App Store secret keys to validate their authenticity for you. Head over to the Add-ons section, where you'll be able to find the platforms supported for receipt validation: Amazon (under Monetization), Apple and Google (under Platforms).

PlayFab-Integration160 SIS-PlayFab-Integration170 PlayFab-Integration180

Click on the platforms you would like to use and enter the credentials necessary for receipt validation. If you've successfully activated them, they should show a green label saying that.

tip

If you've followed the guide until now and only want to use receipt validation, you've made it! No other steps are required for you at this point. Please play-test your game with 'Development Build' enabled and check that purchases are actually getting verified correctly.

On the other hand, if you would like to use the full PlayFab suite, keep 'Validation Only' unchecked and continue with this guide. There are still a few steps waiting for you - please follow along until the end.

Logging in the user in Unity

With PlayFab being in 'Full Suite' mode (Validation Only off), our DBManager will not save any data locally on the device. This refers to the DBManager's 'StorageType = Memory' mode, which is activated automatically for this, and means that players need to "download" their own data from the PlayFab servers each time your app is launched. This complies with a high-security app environment, as there is no local data or any save games regarding in-app purchases that could be tampered with.

However, this also means that players need a way to get their purchase data, and only their data, back whenever they launch the app. That's why users have to log in to the PlayFab servers using their account credentials (requiring an active internet connection), so they can continue playing where they left off. In order to do this, Simple IAP System provides a very basic login scene named 'UserLogin'.

PlayFab-Integration190

At this state, users need to register with their email + password for creating their own account. This account should then be used in subsequent app sessions by logging in with the same credentials. A password recovery method is also provided, in case the user actually entered a valid email address he has access to.

An exception to this login technique are platforms which already have a common authentication system, such as Facebook and Steam. By design, users on these platforms are already signed in before they open the app. This is why instead of using the approach described above there too (effectively doubling the registration process), the existing authentication system is used to auto-login the user - they do not need to enter anything and their PlayFab account is connected automatically, even when logging in from different devices.

Remember, since the login scene should now be the first scene of your app, it needs to contain the IAPManager and PlayFabManager prefabs for initialization purposes, but also be declared as the first scene in your Build Settings:

PlayFab-Integration200

Feature Overview

Now that we've implemented PlayFab user management, in this chapter we're going to take a look at what we can do with that integration.

Receipt Validation

Receipt validation happens whenever users purchase a product in the shop. When using the 'Validation Only' mode, only purchases for real money are being validated at the time they happen - however, the result is not really synced with PlayFab, but directly saved to the device. In 'Full Suite' mode, both real money and virtual purchases, as well as the result (e.g. inventory and virtual currency balances) are synchronized with PlayFab - nothing exists locally on the device.

Validating purchases with PlayFab allows you to go into great detail about monetization, track purchase amounts across platforms and even inspecting single users on what they bought in your game. For a more aggregated summary on what your users are buying in your game, along with how often they do it, you can set up a query in the Analytics section for a bar chart analysis.

PlayFab-Integration210

PlayFab-Integration220

PlayFab-Integration230

Cloud Save (Full Suite mode)

Since all transaction related actions are acknowledged by the PlayFab servers, they are registered on the user's PlayFab account. In the user's perspective this means that, combined with a login system described in the last chapter, users can switch devices, uninstall & reinstall the app, still retrieve their data and continue playing without any loss of data (more on synchronization in the next chapter). In an administrator's perspective (yours), having everything flowing over PlayFab's servers allows you to control virtual currency economies, modifying currency balances or inventory of hacking users, banning their accounts, giving out product keys as promotions or just looking at what your players are doing.

PlayFab-Integration240

Introducing Sales (Full Suite mode)

Temporary sales for products could be a way to make specific items or purchases in general more appealing - the big benefit here is that you can introduce IAP sales without updating your app. If you know you would like to run sales in the future, just check 'Fetch' for both real money and virtual products in the IAP Project Settings.

PlayFab-Integration250

What this does is not only fetching and displaying prices of real money products from the App Stores, but also downloading current prices from your title's economy catalog in PlayFab. So in order to run a sale for a specific product, just open it in PlayFab's catalog and edit its price. The new price will be effective when users relaunch your app.

PlayFab-Integration260

In-game Synchronization

Many game actions are automatically synchronized with PlayFab at the time they happen in your app. This applies to everything that requires an interaction with PlayFab's servers, basically. For example, these are the actions which get auto-synced:

  • user purchases real money product (product is assigned to inventory)
  • user purchases virtual currency (currency amount is updated)
  • user purchases virtual product (currency amount is updated, product is assigned to inventory)
  • user purchases virtual product with usage count (currency amount is updated, usage is updated in Player Data (Title))
  • user selects/unselects product (selection value is updated in Player Data (Title))

PlayFab-Integration270

As you can see, most of the shop synchronization is handled for you already. What Simple IAP System cannot know though, is what you are doing with these items in your game. This means that everything dependent on your own game-specific use case also has to be handled and synchronized by you. The PlayfabManager (link to Scripting Reference) provides several methods, described below, for syncing your data back to PlayFab. Each method is explained with a sample use case and the point when it's best to call it.

SetPurchase

Use case: the player finds a new weapon in-game and you would like to give it to him for free. Note that this method is best suited for non-consumable products, as for consumable products you should call the other methods directly to minimize web requests. When: at any point during the game.

SetPlayerData

Use case: the player previously bought some power-ups with usage count. He then activates them in-game, which you are tracking via DBManager.IncreasePlayerData by passing in a negative value (to substract the power-up usage count). You then want to synchronize the remaining usage count with PlayFab by calling this method. When: only at the end of a round or level, to minimize web requests.

SetFunds

Use case: the player collects coins during the game, which you are tracking via DBManager.IncreaseFunds. You then want to synchronize the current currency amount with PlayFab by calling this method. When: only at the end of a round or level, to minimize web requests.

SetSelected

Use case: you have an in-game inventory display where players can select and deselect e.g. weapons. Note that the selection in the shop scene is synced for you already. When: at any point during the game.

Adding Cloud Scripts

Some of the methods listed in the previous chapters are calling custom code on PlayFab's servers, referred to as "cloud scripts". Each title on PlayFab has its own server code section hosted on Microsoft Azure using Functions, where you can execute actions which should not be in the hands of users (to prevent hacking), such as granting products or virtual currency, or just to add another security measure by checking the values it receives for feasibility. You have to setup some Azure functions with the code mentioned below, so that Simple IAP System is able to properly call them for your title. Note that the Microsoft Azure subscription includes a generous free tier for calling and executing functions.

In the (Azure Portal), create a new Functions application with an unique URL. When created, it should look similar to this:

PlayFab-Integration280

Under the Configuration section, add a 'PLAYFAB_DEV_SECRET_KEY' variable with the value found in your PlayFab's Title, under 'Title settings > Secret Keys > Secret Key'. If there is no Default Key yet, create one first. This key serves as an authorization mechanism for allowing your Azure functions to call the PlayFab API.

PlayFab-Integration290

Next, set up a Visual Studio or Visual Studio Code project for Functions deployment. For more information on how to create a project for this, please see (the official quickstart documentation). In this project, add a 'PlayFabFunctions.cs' file and copy-paste the code included in SIS, located at 'SimpleIAPSystem > Extensions > PlayFab > Scripts > CloudScript.txt'. Note that there are a few NuGet packages required as described in the quickstart guide, namely the PlayFabAllSDK and PlayFabCloudScriptPlugin packages. Additionally, add a 'CS2AFHelperClasses.cs' file with the code found (on this respository).

With the function code deployed to Azure, you should see a 'addCurrency' and 'grantItems' function in your application dashboard. For each function, open it and copy the function URL.

PlayFab-Integration300

In PlayFab, register these functions with a HTTP trigger and insert the URL copied from Azure before.

PlayFab-Integration310

PlayFab-Integration320

tip

Congratulations, you've made it to the end!