# Cocos2dx Quick Start

This guide will show you how to integrate the Frameplay plugin into your Cocos2dx project.

We officially support:

Cocos2d-x 3.17
Windows, Mac, Android & iOS platforms

# Prerequisites

Before getting started you must create a Developer Account (opens new window) and a Game (opens new window) on the Frameplay Platform.

Install Cocos2d-x 3.17 and created a project. Read more about configuring Cocos 2dx projects here (opens new window).

# Getting Started

# Download and Install the Frameplay Plugin

Download the latest version of the Frameplay Cocos2d-x plugin from the Frameplay Platform downloads page (opens new window)
Unzip the folder and copy the Frameplay and Resources folder into your project's root directory.

# Initialize the Frameplay SDK

Initialize the Frameplay SDK by calling frameplay::initialize. This starts a Session and creates a secure runtime connection to the Frameplay server.

Set the gameId parameter to your Game ID found on the Frameplay Dashboard Game Page (opens new window)
Enter your application name into the build_name parameter. (No special characters allowed)
Enter your build version into the build_version parameter in the form of x.y or x.y.z.
Set the frameplay::sdk_mode parameter to test during development. This ensures you load mock ads and analytics will be gathered on your Test Dashboard (opens new window)
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)
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",
  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);

Load our Example Scene from your AppDelegate class for a demonstration of SDK initialization.

#include "Frameplay/FrameplayExampleScene.h"

auto scene = FrameplayExampleScene::create();

# Create an Ad Space

An Ad Space is the Node that will display the intrinsic advertisements to the player.

Configure the Ad Space Content:

Set the image ratio to one of our preset aspect ratios to best fit your environment
Set the texture quality multiplier to your required texture quality.
Set the refresh type to either dynamic or static (Dynamic ads will refresh a new ad every 60 seconds. Static will only request a single advertisement)

#include "frameplay.h"
const content_configuration content_config{
  frameplay::image_ratio::_16x9,
  frameplay::texture_quality_multiplier::original,
  frameplay::refresh_type::dynamic_content,
};

Configure the Ad Space Name to a uniquely identifiable name. Be as descriptive as possible by including the Ad Space context or the Scene name where the Ad Space is rendered.

#include "frameplay.h"
const ad_space_configuration ad_space_config{
  "Level-1 Ad Space",
  content_configuration,
};

Create the Ad Space and set the Ad Space size using the height or width property. (Ad Spaces will remain in their fixed aspect ratio to ensure the advertisement display remains valid)

#include "frameplay.h"
const auto ad_space = frameplay::ad_space::create(ad_space_config, frameplay::height(100));

Set the Ad Space position using the x & y coordinates
Add the child node to your scene graph

#include "frameplay.h"
ad_space->setPosition(200, 100);
//Add child to the Scene Graph
this->addChild(ad_space);

Load our Example Scene from your AppDelegate class for a demonstration of Ad Space creation.

#include "Frameplay/FrameplayExampleScene.h"
auto scene = FrameplayExampleScene::create();

# Configure Project Properties

Follow our guides to configure your project properties for your Operating System and Build Target Platform (Windows, OSX, iOS & Android):

Windows
Mac

# Load a Mock Advertisement

Build and run your Cocos2d-x application. When the Ad Space Node is spawned and visible it will request, download and display a mock advertisement.

Congratulations! You have created your first intrinsic advertisement.

# View Impression Data

Sessions started in-editor and in development builds will automatically run in Test Mode and mock advertisements will be used.

Impression data gathered in Test Mode will display on the Test Dashboard (opens new window) and will not yet generate revenue.

# Packaging Builds

When building for production, set the frameplay::sdk_mode parameter to release when initializing the SDK.

const frameplay::sdk_configuration config{
  game_id,
  frameplay::sdk_mode::release,
  ...
};

Submit your account and game for approval on the Frameplay Platform:

Please allow 48 hours for approval. Advertisements will not load in Production builds until both your account and game is approved.

At this time our integration team will contact you. Once approved, your Ad Spaces in your production build will load advertisements, earn revenue and analytics will be recorded on the Live Dashboard (opens new window).

# Best Practices

We highly recommend you check out the Best Practices Guide to maximize revenue, impression quality and user experience!

# Troubleshooting

If something went wrong during setup, check console logs for details and visit our FAQ page.

Windows →