Sessions & Cameras

When the Frameplay SDK is initialized a Session & runtime connection to our servers is created. This Session is used for reporting on the Frameplay Dashboard (opens new window)

Starting a Session

Initialize the Frameplay SDK to create a Session & runtime connection to our servers. This only needs to be called once before gameplay begins and is required for ads to load.

Initialize by calling the method frameplay::initialize with the following parameters:

1. Set the gameId to your Game ID value found in the Frameplay Dashboard Game Page (opens new window) This ensures your project is linked to your Game, on our Dashboard
2. Enter your application name into the build_name parameter. (No special characters allowed)
3. Enter your build version into the build_version parameter in the form of x.y or x.y.z.
4. Set the frameplay::sdk_mode parameter to test during development. This ensures you load mock ads and test analytics will be gathered on the Dashboard (opens new window)
5. Set the global_texture_quality parameter to your required global Ad Space texture quality (optional)
6. Configure the global_texture_quality parameter. This controls the downloaded advertisement file sizes. (optional)
7. Configure the player parameter with the current player details. (If available, the players Age and Gender should be passed as parameters. These can be sourced from a client API or a custom login)
8. Set the Allow Data Collection player parameter. This corresponds to the respective platform signal Limit Ad Tracking.

#include "frameplay.h"

// Create the configuration objects
const frameplay::settings settings{
  "my_game_id",
  "my_game",
  "1.0.0"
  frameplay::sdk_mode::test,
  frameplay::global_texture_quality::medium
};
const frameplay::player player(frameplay::data_collection::allow);

// Start the Frameplay SDK
frameplay::frameplay::initialize(settings, player);

Code examples can be found in our SDK demo scene: Frameplay\FrameplayExampleScene.h

Session Parameters

Game ID

The Game ID value is found in the Frameplay Dashboard, on your Game Page (opens new window) This ensures your project is linked to your Game on our Dashboard.

Game Name & Version

The Game Name and Game Version parameters are used as part of network requests from the Frameplay SDK. They do not need to conform to a specific format. Game Version usually takes the format x.y or x.y.z however. Please avoid the use of special characters in these parameters.

SDK Mode

The SDK Mode parameter determines the environment: test or release.

During development ensure sessions are run with the frameplay::sdk_mode::test value. This will load mock ads in your Session and analytics will be gathered on your Test Dashboard (opens new window).

When publishing a production build, set the frameplay::sdk_mode::release parameter. This will ensure your Ad Spaces request real advertisements and analytics will be recorded on your Live Dashboard.

Global Texture Quality

The Global texture quality determines the advertisement texture size. Set to either quarter, half or original.

All advertisement images will be under 2MB when downloaded at runtime. (Actual texture memory usage (VRAM) being higher.)

This global configuration - combined with the Ad Space quality setting - controls the downloaded advertisement file sizes and maximum resolution parameter to control the ad download texture quality.

Cache Size

The Cache Size controls how the Frameplay SDK caches ad content in memory. If we serve the same ad content to a player multiple times, serving it from the cache instead of the network provides a performance boost. This parameter is measured in number of textures stored in memory; set it to 0 to disable the runtime cache. Each texture cached will occupy ~200KB to ~2MB in space.

Player

The player Age, Gender can be optionally sourced from a client API or a custom login. This data allows for targeted advertisements.

The Allow Data Collection parameter corresponds to the "Limit Ad Tracking" signal (e.g. iOS, Android). False: User has not opted-in tracking is limited per commercial guidelines, or True: User has opted-in tracking is unrestricted.

Camera

The Frameplay Session uses a Camera for gathering metrics. Only one Camera Object can be registered at a time.

By default, the Session will use the Scene's default camera, or the camera provided in the frameplay::initialize method call.

Cameras can be registered and unregistered when required with the frameplay::set_camera function.