iOS InApp cocos2dx Documentation - yanivav/Documentation GitHub Wiki
Last SDK Version: 2.4.0
This document describes the basic procedure for integrating StartApp In-App Ads into your Cocos2d-x applications for iOS.
After this simple integration process, StartApp In-App Ads enables you to reap the benefits of StartApp's In-App monetization products, which maximize the revenue generated by your application. All this profit-making is achieved with minimal effort and minimal interference with your users’ experience.
NOTES:
- The code samples in this document can be copy/pasted into your source code
- When submitting your application to the App Store,do not forget to update your "IDFA Settings"
- If you have any questions, contact us via [email protected]
##Step 1, Adding the StartApp SDK and StartApp Cocos2d-x plugin to your project
In order to add StartApp SDK to your application please follow the following steps:
1. Unzip the SDK files to a temporary folder
2. Drag and drop StartApp framework, StartApp bundle, StartApp_Cocos2DX_x_x_x.a and StartAppPlugin.h to your project
_CoreTelephony.framework_
_SystemConfiguration.framework_
_CoreGraphics.framework_
_StoreKit.framework_
_AdSupport.framework_
_QuartzCore.framework_
##Step 3, Initialization In your application delegate class (_AppDelegate.cpp_), include the StartApp SDK and add the following lines to your application's ``didFinishLaunchingWithOptions`` function:
// AppDelegate.cpp
#include "StartAppPlugin.h"
bool AppDelegate::applicationDidFinishLaunching()
{
startappiOS* startAppBridge = startappiOS().sharedInstance();
startAppBridge->STAInit("your app Id", "your developer id");
return true;
}
Replace "Your Account Id" and "Your App ID" with your own values provided in the developers’ portal.
After logging in, your account ID will be displayed at the top right-hand corner of the page:
To find your application ID, click on the "Apps and Sites" tab on the left pane and choose the relevant ID from your app list:
StartApp SDK provides two modes for displaying Splash screens:
Splash Screen Mode | Description |
---|---|
User-Defined Mode (default) | Using your application's default splash image, with a loading animation |
Template Mode | StartApp SDK provides a pre-defined template in which you can place your own creatives, such as application name, logo and loading animation. for more details, please refer to the "Advanced Manual" |
####Adding the Splash Screen
In your application delegate class (AppDelegate.cpp), after initializing the SDK, call the showSplashAd
method:
// AppDelegate.cpp
#include "StartAppPlugin.h"
bool AppDelegate::applicationDidFinishLaunching()
{
startappiOS* startAppBridge = startappiOS().sharedInstance();
startAppBridge->showSplashAd();
return true;
}
If you wish to customize or use a different splash screen, please refer to the Advanced Usage.
##Showing Interstitial Ads ######You can choose to show the interstitial ad in several locations within your application. This could be between stages, while waiting for an action, when pressing a button and more.First, import the StartApp SDK in your view controller and add the following lines to the cpp file for each view in which you would like to show an ad
// HelloWorldScene.cpp
#include "StartAppPlugin.h"
bool HelloWorld::init()
{
startappiOS* startAppBridge = startappiOS().sharedInstance();
startAppBridge->loadAd();
return true;
}
Then, just add the following line where you want to show the ad
startAppBridge->showAd();
##Return Ads The **Return Ad** is a new ad unit which is displayed once the user returns to your application after a certain period of time. To minimize the intrusiveness, short time periods are ignored. For example, the Return Ad won't be displayed if the user leaves your application to take a short phone call before returning.IMPORTANT
Loading an ad might take a few seconds so it's important to show the ad as late as you can. In case you callshowAd()
while the ad hasn't been successfully loaded yet, nothing will be displayed. For example, if you'd like to show an ad after completing a game's level, the best practice would be to show the ad upon completing the level (for example in yourviewDidDisappear()
function). On the other hand, loading and showing the ad together at the beginning of the next level might result with a failure – as the ad might not have enough time to load.
Return ads are enabled and activated by default. If you want to disable this feature, simply call startAppBridge->disableReturnAd()
as part of the initialization process, in your AppDelegate.cpp file:
// AppDelegate.cpp
#include "StartAppPlugin.h"
bool AppDelegate::applicationDidFinishLaunching()
{
startAppBridge->disableReturnAd();
return true;
}
Then, call loadBanner
in the view controller where you want the banner to be displayed.
startAppBridge->loadBanner(startappiOS::STAAdOrigin_Bottom,
startappiOS::STA_AutoAdSize);
Value | Position | Behaviour |
---|---|---|
STAAdOrigin_Top |
Auto Top | The banner will be centered and pinned to the top of the view. In case the view is a root view controller, the banner will be located under the status bar, if exists. |
STAAdOrigin_Bottom |
Auto Bottom | The banner will be centered and pinned to the bottom of the view. |
##Enjoy Higher eCPM with Demographic-Targeted Ads If you know your user's gender, age or location, StartApp can use it to serve better-targeted ads which can increase your eCPM and revenue significantly.NOTE
If you wish to use a fixed origin for the banner, please refer to the "Advanced Manual"
####Set Age and Gender Upon initialization, after providing your DevId and AppId, add the age and gender:
startAppBridge->STAInit("your app Id", "your developer id", "user age", "user gender");
- Replace "user age" with the user's real age
- Replace "user gender" with the user's real gender, using STAGender_Male or STAGender_Female.
Example - for a 22 years male use:
// AppDelegate.cpp
#include "StartAppPlugin.h"
bool AppDelegate::applicationDidFinishLaunching()
{
startappiOS* startAppBridge = startappiOS().sharedInstance();
startAppBridge->STAInit("1234", "5678", 22, startappiOS::STAGender_Male);
return true;
}
(replace "1234" and "5678" with your REAL developer Id and App Id)
####Set Location The location of the user is a dynamic property which is changed constantly. Hence, you should provide it every time you load a new Ad, uasing the STAAdPreferences object:
startappiOS::STAAdPreferences *pref = new startappiOS::STAAdPreferences();
pref->userLocation.longitude = 32.44444;
pref->userLocation.latitude = 30.2222;
startAppBridge->loadAd(pref, STACallbacks);
On the "Advertising Identifier" section:
1 Choose "Yes" on the right pane
2 Opt-in the "Serve advertisements within the app" checkbox
3 Opt-in the confirmation checkbox under "Limit Ad tracking setting in iOS"