Documentation

Did you find this helpful?

3rd Party Integration Guide: IronSource

This guide shows how to integrate IronSource into your PlayFab project.

Important notes: 

  • This guide uses Android platform for testing. If you pick another platform, just change the stack of required plugins for your needs.
  • While IronSource offers several types of AD Units, we will only illustrate Video ADs integration. The approach is similar to every other AD Unit type. Please consult with IronSource SDK documentation on how to display and intercept different AD Units.
  • The following versions were used to test this guide:
    • Unity 2017.1.0f3
    • IronSource Unity SDK Plugin 6.6.4
    • PlayFab Unity SDK 2.26.170814
    • Unity configured to Target API Level Android 7.0 'Nougat" with Minimum API Level of Android 4.1

Known issues:

  • Targeting Android API Level >= 7.0 causes application to freeze on start with no errors due to IronSource plugin <= 6.6.5. Please, inspect update logs on IronSource Unity SDK for when the fix is released.

Prerequisites:

General Integration Flow

IronSource and PlayFab integration is based on sharing AD-related responsibilities. IronSource provides material for the ADs such as videos and images that will be introduced to the user. PlayFab provides reward delivery system that fits nicely into PlayFab ecosystem: player may be granted items, improved statistics, or any other custom Cloud Script code can be run to reward the player. The benefit is that client is not used to run any reward code. Client only notifies PlayFab and the rest is handled server side.

To integrate successfully, developer must define AD Placements in each system (PlayFab and IronSource) with matching names:
To be rewarded for IronSource DefaultRewardedVideo, the same Ad Placement must be defined in PlayFab.

Both services can be used to fetch available AD Placements: IronSource offers PUSH mechanism notifying the client about ADs that is available at the moment PlayFab offers PULL mechanism allowing client to get the list of AD Placements and check for it's availability.

Both systems have different AD-limitation components (capping and pacing). To avoid inconsistency, it is recommended to configure limitations using PlayFab. This will effectively secure AD-delivery, which is what player wants to exploit.

The rest of the guide shows step-by-step integration example.

Setting up IronSource Application

Once you have signed into IronSource, navigate to the internal developers console. Navigate to "Apps" tab (1) and click "New App" (2):

A form will pop up. Depending on your application state, you should select the right option for you. This guide assumes you do not have an application in production yet, so select "App Not Live in the Application Store" (1). Give your app a temporary name (2). Select your platform (3). Commit by clicking "Add App" (4):

A configuration page will pop up. In this guide we will test Rewarded Video Ad Unit. Please, make sure it is test-enabled (1). Commit by clicking "Done" (2):

You will be brought back to application list. Click configuration button (1):

Make sure "Rewarded Video" sub-tab (1) is selected. Make sure the ad unit is test-enabled (2). Observe the existing default AD placement: "DefaultRewardedVideo" (3). It is sufficient on it's own. Just to show customization options, let's create our own AD placement. Click "New Placement" (4):

Give a name for your placement (1). Set custom reward to something that indicates the reward is managed by PlayFab (2). Make the reward amount (3) greater or equal to 1 to make IronSource happy. Finally, commit by clicking "Save" (4).

Note: In this guide "RESERVED_BY_PLAYFAB" reward is purely for our own awareness and does not effect anything. We simply never use the reward information from IronSource - reward delivery is handled entirely on PlayFab side and will only require Placement Name. 

Observe both placements available in the list (1):

This concludes configuring IronSource app. You might want to keep the configuration page opened, as some information will come in handy later in the guide.

Setting up PlayFab Title

Open Game Manager for your title. Navigate to "Ads" tab (1). Then navigate to "Ad Placements" sub-tab (2). Click "New Ad Placement" (3):

Our next steps aim to create a placement matching to what we have in configured in IronSource by name. That's why the next step is to give your placement the exact same name (1) your placement in IronSource has (the image below shows example for "DefaultRewardedVideo" placement). Configure AppId (2) to match your IronSource AppId. Type in the Ad Unit type (3). Finally, commit by clicking "Save & Add Rewards" (4):

A placement configuration page will open. Click "New Reward" (1):

Give your reward a name (1). Optionally, you may set up package URL (2). This field is pretty generic and may contain any resource URL (ex. preview image). Observe how reward exposes Action Group interface (3). Add new action. In this example, we will increment statistic, but you definitely can execute any set of actions you want. Configure the action to suit your needs (4). Commit by clicking "Save Reward" (5).

Placement configuration will open again. Observe how your reward is now in the list (1). Also, notice that placement may have several rewards configured: one will be randomly selected based on the odds. Weight setting will define the odds in relation to the rest of rewards. Notice also that you may configure Reward Limits (2). Observe how rewards may be overridden for a specific segment (3). Finally, click "Save Placement" (4) to commit:

Placements list will open. Repeat the steps above to create one more Placement matching "PromoVideo" placement from IronSource. Finally, ensure that you have 2 placements with names matching to what you have defined in IronSource (1) :

This concludes configuring PlayFab title.

Android: faking the Google Play Service

IronSource has indirect dependency on Google Play Services. For production, you definitely want Google Play Service plugin installed and configured. For testing purposes, however, we may cheat a little. Create a folder/file structure as shown on the picture below:

File at path 'Assets/Plugins/Android/res/values/version.xml' will contain the following code:

<?xml version="1.0" encoding="utf-8"?>
 <resources>
     <integer name="google_play_services_version">8298000</integer>
 </resources>

Generally, this should be enough to make IronSource happy for testing purposes.

Testing

Our final step is setting up adding code for our Unity project and making sure stuff works. Please, check that you have IronSource and PlayFab imported, and PlayFab is configured to use your title.

First, set the up the project as shown on the picture below. Create a script file 'IronSourceIntegrationExample.cs' (1). It will contain our code. Create a scene (2) and do not forget to add it to build settings. Create an game object (3) and give it some name. Make sure to add two components to this game object: 'IronSourceEvents' (4), which comes from IronSource SDK and 'IronSourceIntegrationExample' (5), which is our code:

Next, fill 'IronSourceIntegrationExample.cs' with the following code (please, refer to comments for further information). Remember to fill '_YOUR_IRONSOURCE_APP_KEY_' placeholder:

using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;
using PlayFab;
using PlayFab.ClientModels;
using UnityEngine;

public class IronSourceIntegrationExample : MonoBehaviour {
    private const string AppKey = "_YOUR_IRONSOURCE_APP_KEY_";

    // This will contain a list of available ad placements
    public Dictionary<string, AdPlacementDetails> AdPlacements { get; set; }

    // Start by initializing both SDKs
    void Start() {
        InitializePlayFab();
        InitializeIronSource();
    }

    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));

        // Add button to refresh Ad Placements
        if (GUILayout.Button("Refresh AD Placements")) RefreshAdsList();

        GUILayout.Space(40);

        if (AdPlacements == null || AdPlacements.Count == 0) return;

        // Expose the list available and ready Ad Placements 

        foreach (var ad in AdPlacements.Values) {
            if (GUILayout.Button("Trigger " + ad.PlacementName)) {
                // Consume the Ad Placement
                TriggerAdPlacement(ad);
            }
        }

    }

    // This is executed from GUI code
    private void TriggerAdPlacement(AdPlacementDetails ad) {
        // Tell ironSource to show us a reward video for a specific Placement
        IronSource.Agent.showRewardedVideo(ad.PlacementName);
    }

    // This is invoked from UI code and when PlayFab is logged in.
    // This method refreshes list of available ADs placements
    private void RefreshAdsList() {
        PlayFabClientAPI.GetAdPlacements(new GetAdPlacementsRequest() {
            AppId = AppKey,
        }, OnAdPlacementsRefreshed, OnPlayFabError);
    }

    // This is invoked when we got a fresh list of Ad Placements
    private void OnAdPlacementsRefreshed(GetAdPlacementsResult obj) {
        // Cache those into a dictionary
        AdPlacements = obj.AdPlacements
            // Filter those that can be shown
            .Where(p => !p.PlacementViewsRemaining.HasValue || p.PlacementViewsRemaining > 0)
            // Create a dictionary where PlacementName is mapped to the rest of the data
            .ToDictionary(p => p.PlacementName);
    }

    private void InitializePlayFab() {
        // Initiate login call
        PlayFabClientAPI.LoginWithAndroidDeviceID(new LoginWithAndroidDeviceIDRequest() {
            CreateAccount = true,
            AndroidDeviceId = SystemInfo.deviceUniqueIdentifier // You may want to use different approach in production
        }, OnLoggedIn, OnPlayFabError);
    }

    private void InitializeIronSource() {
        // Initialize ironSource SDK with an App ID and AD units. You may add more AD units as you go.
        IronSource.Agent.init(AppKey, IronSourceAdUnits.REWARDED_VIDEO);

        // Set the user id. In production, you should use special Advertising User ID, usually granted by the platform
        // ex https://support.google.com/googleplay/android-developer/answer/6048248?hl=en
        IronSource.Agent.setUserId("TestAdUserID");

        // Make sure we are good to go.
        IronSource.Agent.validateIntegration();

        // Subscribe to an event where user has been granted a reward from ironSource standpoint
        IronSourceEvents.onRewardedVideoAdRewardedEvent += placement => {
            // And propagate it to PlayFab if we are logged in
            if (!PlayFabClientAPI.IsClientLoggedIn()) return;
            var placementName = placement.getPlacementName();

            // Not tolerate unknown placements
            if (!AdPlacements.ContainsKey(placementName)) {
                throw new Exception("Unknown placement name");
            }

            // Get placement info from Cache
            var placementInfo = AdPlacements[placementName];

            // Trigger PlayFab to reward us for the activity
            PlayFabClientAPI.RewardAdActivity(new RewardAdActivityRequest() {
                PlacementId = placementInfo.PlacementId,
                RewardId = placementInfo.RewardId
            }, OnRewardActivityComplete, OnPlayFabError);
        };
    }

    // This is invoked when PlayFab log in complete
    private void OnLoggedIn(LoginResult obj) {
        Debug.Log("Logged in with PlayFab");
        RefreshAdsList();
        // Request list of available ads:
    }



    // This is invoked when User was rewarded from PlayFab standpoint
    private void OnRewardActivityComplete(RewardAdActivityResponse obj) {
        Debug.LogFormat("Reward obtained for placement {0}", obj.PlacementName);
    }

    // This is invoked to handle any PlayFab error
    private void OnPlayFabError(PlayFabError obj) {
        Debug.LogError(obj.GenerateErrorReport());
    }

    // On application pause
    void OnApplicationPause(bool isPaused) {
        // propagate it to the IronSource SDK
        IronSource.Agent.onApplicationPause(isPaused);
    }
}

Next, let's check the build settings. Make sure that 'Android' platform is selected (1). Make sure to have a well looking Package Name (2). Finally, if you are using IronSource Unity Plugin <= 6.6.5, please make sure target API Level (3) 7.0 or lower:

Run the application on your device as usual. Observe the UI and click (1) to trigger one of your placements:

Watch the ads playing, then click close (1):

Finally, navigate to your Game Manager Dashboard and ensure appropriate events are recorded (1):

Now you have successfully integrated IronSource into your PlayFab Application.



Did you find this helpful?