# 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 ofx.y
orx.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 signalLimit 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 eitherdynamic
orstatic
(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
orwidth
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 coordinatesAdd 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):
# 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 torelease
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:
- Submit Developer Account for approval (opens new window)
- Submit Game for approval (opens new window)
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 →