iOS and Android: Google Consent SDK

Mark Alexander
  • Updated
Follow

Under the Google EU User Consent Policy, you must make certain disclosures to your users in the European Economic Area (EEA) and obtain their consent to use cookies or other local storage, where legally required, and to use personal data (such as AdID) to serve ads. This policy reflects the requirements of the EU ePrivacy Directive and the General Data Protection Regulation (GDPR).

To support publishers in meeting their duties under this policy, Google offers a Consent SDK. The Consent SDK is an open-source library that provides utility functions for collecting consent from your users (the full source code is available on GitHub).

Ads served by Google can be categorised as personalised or non-personalised, both requiring consent from users in the EEA. By default, ad requests to Google serve personalised ads, with ad selection based on the user's previously collected data. Google also supports configuring ad requests to serve non-personalised ads (you can learn more about personalised and non-personalised ads here).

This guide describes how to use the Consent SDK along with GameMaker and the Google Services Extension to obtain consent from users. Note that if you have not previously set up your AdMob dashboard and created at least one test ad, then we recommend you complete the following guide before continuing, as it will familiarise you with the AdMob dashboard, as well as give you ads on which to test the Consent SDK:

 

Setting Up AdMob

Before we can get to adding the Consent SDK to your game, we first have to set up the Blocking Controls on your AdMob dashboard. Due to limitations in Google's built-in consent form (which this extension uses), you cannot use the Consent SDK under the following circumstances:

  • If your AdMob setup uses more than 12 ad providers

  • If your AdMob setup uses mediation

  • If your AdMob setup uses the default list of ad providers

With these limitations in mind, we will explain how to set up the AdMob dashboard so that you can use the Consent SDK in your game.

NOTE: Due to Google's Consent SDK being open-source, you should be able to create a custom consent form if required to cover any of the above-listed cases. See here for more details.

The first thing to do is go to your AdMob dashboard and click the main Blocking Controls menu item. Note that this is the global blocking controls item, and not the per-app blocking controls item:

AdMob_BlockingControls.png

Here you need to select the EU User Consent section (if it's not visible at the top of the page then click the > button until it shows):

AdMob_EUUserConsent.png

Under the section Select Ad Technology Providers choose "Custom set of ad technology providers":

AdMob_CustomTech.png

You then need to click the Select Providers button to open the ad providers window, which will list all the available providers through AdMob, of which you can select up to 11 (to make 12 total, as Google is an obligatory provider):

AdMob_CustomProviders.png

With that finished, click the "Done" button and then scroll down the page and take note of the Publisher ID, as you'll need that to use in GameMaker:

AdMob_PublisherID.png

You can now click the Save Changes button to confirm everything, and then open Game Maker.

 

Setting Up GameMaker

The Consent SDK is bundled as part of the AdMob extension, which in turn is included as part of the Google Play Services extension. This means that to use the Consent SDK you should have already installed the Services extension, and set up at least one test ad through Admob. If you haven't done any of those things then please see this article before continuing:

The Consent SDK is initialised when you call the function GoogleMobileAds_Init(), so all consent functions should be called only after you have called that. Which functions you call will depend on how you have your game set up, but for the sake of this tutorial, we'll show how to use a test device as well as how to get consent information and show the consent form.

 

IMPORTANT NOTE FOR iOS

Due to the current limitations of the GameMaker extension system, you will be required to perform some extra steps every time you test or build your game to get the Consent SDK to function correctly. This will be fixed in a future IDE update.

  • To start with you need to check the option "Suppress Build and Run" in the Preferences > Platform Settings > iOS as we will need to edit the Xcode project before running.

  • You will also need to download the iOS Consent SDK and unzip it to a safe location on your Mac. You can get it from here (the current extension works with v1.0.3): https://github.com/googleads/googleads-consent-sdk-ios/releases
  •  Finally, locate the "PersonalizedAdConsent.bundle" folder, as this is what we'll need to add to Xcode.

You can continue to set up the consent form functions as shown in the rest of this article, and when you try to test or build your game, it will be pushed to Xcode, but won't run. At this point you need to drag the "PersonalizedAdConsent.bundle" onto Xcode to add it to the project and then run it from Xcode. It should now build and run and show the consent form correctly.

 

Showing The Consent Form

To show the consent form, you'd generally have something like this in the Create Event of the fisrt object in your game:

ads_app_id = "ca-app-pub-4337965866269847~8824553239";
ads_consent_id = "pub-1564346280128643";
ads_device_id = "57BFBCB8E9A1AAA0CDEA08E925D11960";
ads_privacy_url = "https://www.yoyogames.com/legal/privacy";
GoogleMobileAds_Init("", ads_app_id);
GoogleMobileAds_ConsentDebugAddDevice(ads_device_id);
GoogleMobileAds_ConsentDebugSetDeviceInEEA(true);
GoogleMobileAds_ConsentUpdate(ads_consent_id, ads_privacy_url, true, true, true);

As you can see, first we set up the test device and then we set the device to be located in the European Economic Area (EEA). If you don't specify a test device to use, then the function to set the device as being in EEA will fail, and the actual device location will be used.

NOTE: You can get your test device ID from the console output when you run the game with ads enabled. Look for a line that says:

Use AdRequest.Builder.addTestDevice("E3DAE5ACA5072BA37337B94E287527C9") to get test ads on this device

We then call the function GoogleMobileAds_ConsentUpdate(), which will first check to see if there are any consent details already cached for the given publisher, and if not it will show the consent form. The function requires you to supply the following arguments:

  • Publisher ID: This is the publisher ID that you got from the Google AdMob dashboard (a string). 

  • Privacy Policy URL: This is a full URL that links to the Privacy Policy that you want to use.

  • Personalised Ads: When set to true, the user will be presented with the option to see personalised ads.

  • Non-Personalised Ads: When set to true, the user will be presented with the option to see non-personalised ads.

  • Ad-Free: When set to true, the user will be presented with the option to see an ads-free version of your game.

Note that you can show the consent form without checking for cached data by calling the function GoogleMobileAds_ConsentFormShow(), but the data returned will not be cached and you will be required to call the update function with the returned values to cache them for future sessions. In general, you should only need to call the update function, however.

 

Getting Consent Data

The functions shown above will trigger a Social Asynchronous Event, which will populate the built-in async_load DS map with the following key/value pairs:

  • "type" - This is used to identify the type of event being called, and for the consent SDK it will be "consent_status".

  • "id" - This will be the built-in constant GoogleMobileAds_ASyncEvent, and is used to identify the event kind that has been triggered.

  • "status" - This represents the user's choice when it comes to personalised ads. If "non_personalized" has been selected, the user should not be shown any personalised ad content. Note that this key will not exist if the "error" key exists. The possible return values are:
    • "UNKNOWN"
    • "NON_PRESONALIZED"
    • "PERSONALIZED"

    Note that if the status is "UNKNOWN", then the SDK will attempt to show the consent form to the user. Also note that if the user selects non-personalised ads, then they will be shown an additional form to which they must agree.

  • "ad_free" - This will either be 0 or 1. If set to 1, the user prefers an ad-free version of the app, in which case you can perform a url_open on the store page for the paid version of the app, or show some other kind of up-sell interface within the game.

  • "error" - This reports any errors encountered while updating/querying the players consent, or while showing the consent form.

You can then parse this map data in the Async event and react accordingly. Note that if you choose to show a button to attract users to a paid version of the game, consent will not have been given to show ads. So, you will still have to show the consent form again if the user keeps using the app and you want to use ads.

To parse the data, you would have something like this:

if async_load[? "id"] == GoogleMobileAds_ASyncEvent
{
if async_load[? "type"] == "consent_status"
    {
    if ds_map_exists(async_load, "error")
        {
        // Error handling here
        }
    else
        {
        if async_load[? "status"] == "PERSONALISED"
            {
            GoogleMobileAds_ConsentSetAllowPersonalizedAds(true);
            }
        else if async_load[? "status"] == "NON_PERSONALISED"
            {
            GoogleMobileAds_ConsentSetAllowPersonalizedAds(false);
            }
        else // async status == "unknown"
            {
            if async_load[? "ad_free"] == 1
                {
                // Open a URL on the paid app, or go to an up-sale menu, etc...
                }
            }
        }
    }
}

Note that the consent form itself doesn't actually change how ads are displayed, it simply retrieves the consent data, and you are required to use the GoogleMobileAds_ConsentSetAllowPersonalizedAds() function to actually tell the AdMob SDK what consent has been given, which in turn will change the ads content served.

 

Consent And Age

In the EEA, the different member states have an age limit at which it is required parental permission to be shown ads. This age is generally between 13 and 16, and so the consent SDK has an option to set (and get) an "underage" flag, using the following two functions:

  • GoogleMobileAds_ConsentSetUserUnderAge()
  • GoogleMobileAds_ConsentIsUserUnderAge()

When a user is under the age of consent set by GDPR, Google will only serve non-personalized ads to that user, but it's up to you to tell Google that someone is underage or not. This means that you may need to add some way to get the user's age into your game and then use GoogleMobileAds_ConsentSetUserUnderAge() based on the results so that personalized/non-personalized ads can be shown. These functions map to the TFUA flag in the SDK, which you can find out more about here.

Note that if a user is flagged as being under the age of consent, any attempt to show the consent form will fail, and the async DS map "error" key will contain the following:

"Error: tagged for under age of consent."

 

Summary

The general idea here is that you show a form, parse the results of the form input, and then set flags or up-sell as required. The code laid out enough gives you the framework to do this, and is easy enough for you to build on and adapt to your own projects. However, note that there are a few other functions available for the Consent SDK and we recommend that you check the included PDF manual for the extension before going ahead and implementing this fully in a game (you can find it in the "included files" section of the resource tree).

 

 

 

 

 

 

Related articles