ironSource Playable Ad (MRAID)

PlayCanvas supports the ironSource MRAID Playable Ad format and requirements via an official external tool on GitHub.

ironSource playable ads uses the MRAID 2.0 API standard and requires the assets for the ad to be external from the index.html rather than embedded.

The external assets will need to be uploaded to a server or CDN of your own for ironSource to serve the ad on their network.

There are some limitations to be aware of with the tool which can be found in the documentation from GitHub.

Example project

The Cube Jump project is ready to be exported to the ironSource MRAID Playable Ad format and the expected HTML output can be found here.

File size tips

As there is a limit of 5MB (uncompressed), you will have to plan and budget the usage of assets for the ad.

The minified PlayCanvas Engine code is ~1.2MB uncompressed and due to the need to encode the asset files into Base64 strings, it adds ~30% to the size of each asset file.

This means that you would have about ~3MB for assets before the Base64 encoding.

Try to keep images as small as possible in dimensions and use tools like TinyPNG to reduce file size even further.

Playable ad checklist:

Have you added the function call mraid.open (for non-store URLs) or mraid.openStoreUrl (for store apps) as part of your call to action callback?

How to export

Follow the setup steps from the readme in the GitHub repo.

Test with ironSource Playable Test Tool

ironSource have a fantastic test tool here which can be used to go through their checklist of requirements for playable ads.

Check that Testing mode and MRAID are both enabled on the page.

Set the following options in the config.json as shown below. This will produce a ZIP file with the asset data and PlayCanvas Engine code as separate files from the index.html.

    "one_page": {
        "patch_xhr_out": false,
        "inline_game_scripts": false,
        "extern_files": {
            "enabled": true,
            "folder_name": "assets",
            "external_url_prefix": ""
        },
        "mraid_support": true
    }

We will need to serve the files from a HTTPS endpoint to test with the ironSource's test tool.

Our recommended approach is to host locally and use ngrok to create a https tunnel to your computer that the app can access.

This will give a unique URL for the endpoint that we need to add to the index.html where it is referencing external files.

Modify the end of index.html from:

</style>

    <title>Cube Jump MRAID</title>
    <script src="mraid.js"></script>
    <script src="assets/playcanvas-stable.min.js"></script>
    <script src="assets/one-page-mraid-resize-canvas.js"></script>
    <script src="assets/__settings__.js"></script>
</head>
<body>
    <script src="assets/__start__.js"></script>
</body>
</html>

To (where XXXXXXX is the unique subdomain from ngrok):

</style>

    <title>Cube Jump MRAID</title>
    <script src="mraid.js"></script>
    <script src="https://XXXXXXX.ngrok.io/assets/playcanvas-stable.min.js"></script>
    <script src="https://XXXXXXX.ngrok.io/assets/one-page-mraid-resize-canvas.js"></script>
    <script src="https://XXXXXXX.ngrok.io/assets/__settings__.js"></script>
</head>
<body>
    <script src="https://XXXXXXX.ngrok.io/assets/__start__.js"></script>
</body>
</html>

Test locally on your PC by double clicking on the index.html to ensure that it plays correctly.

If it plays correctly on your PC, we can test on ironSource's test tool by copying the contents of index.html and pasting into MRAID tag area of the test tool.

Click on 'Test Ad' and once it renders, play the ad to reach a CTA button. After pressing the CTA button, the tool should show that all the tests have passed and give you an option to generate a code.

This is used to test on device using their app that is available on both Android and iOS.

Final export for ironSource

When the ad is ready to be submitted for ironSource, upload the external assets to your server or CDN and add the URL in the options in config.json via the external_url_prefix property:

    "one_page": {
        "patch_xhr_out": false,
        "inline_game_scripts": false,
        "extern_files": {
            "enabled": true,
            "folder_name": "assets",
            "external_url_prefix": "https://some-cdn.com/unique-id"
        },
        "mraid_support": true
    }

Follow the process on submitting the playable ad from ironSource's documentation.