AdColony V4VC – ShiVa Engine

AdColony V4VC

Nav Gupta: “AdColony V4VC allows you to award your user with coins/virtual currency for watching videos. This is a more advanced tutorial which deals with both Regular Hooks/Callbacks and reverse Hooks/Callbacks and so it will take time to understand, but is worth it for the monetization it brings.”

Read First

– This tutorial is based on the previous Basic tutorial on AdColony for iOS
– Needed for understanding the XCode portion: Reverse Hooks and Callbacks for iOS
– Watch
– Read


– Visit [] and sign up
– Log in and click on Publishers->Setup New App (Green Button)
– Select your platform and store and give your app a title
– Select your ads, but consider your app’s age rating
– You will be given an Application ID and Secret Key in the middle of the page, save those.


– Create a HUD button that calls the following handler:

onShowVideoAd ( bShow )

– Create another handler in your MainAI that is called when AdColony rewards users with coins. In this handler, you simply add coins for the user! We are going to assume you will use your own code to add coins, so we will not write that part of the code as that is your own custom code to add to the total on your end.

onAddCoins ( nCoins )

– Save and export to STK for iOS/XCode


– Visit, log in and download the iOS SDK
– Open the download folder and select the Library folder
– Click and drag the AdColonyPublic.h and libAdColony.a file into your main xCode project area – not the Classes folder, but just outside of that
– Click on your project, then on Build Settings. Add the following under Other Linker Flags:


– Click on the Build Phases tab. Under the Link Binary With Libraries section, click and drag the libAdColony.a file so that it is referenced there. You can also hit the + button to find the file as well. Make sure the following frameworks are referenced:

AdSupport.framework	 OPTIONAL
AVFoundation.framework	 OPTIONAL
CFNetwork.framework	 REQUIRED
CoreGraphics.framework	 REQUIRED
CoreMedia.framework	 OPTIONAL
CoreTelephony.framework	 REQUIRED
EventKit.framework	 REQUIRED
EventKitUI.framework	 REQUIRED
MediaPlayer.framework	 REQUIRED
MessageUI.framework	 REQUIRED
QuartzCore.framework	 REQUIRED
StoreKit.framework	 OPTIONAL
SystemConfiguration.framework	REQUIRED

– Open S3DEngine_Wrapper.cpp and go to approx. line 30. Add the following variable:

static bool bShowVideoAd = false;

– Go down to approx. line 200 (function S3DEngine_iPhone_LoadPack). At the bottom of the callbacks, add the following hook:

S3DClient_InstallCurrentUserEventHook ( "MainAI", "onShowVideoAd", onShowVideoAdCallback, NULL );

– Go up. Outside the function extern “C” bool S3DEngine_iPhone_LoadPack, add another set of functions as follows:

extern "C" bool SetShowVideoAdCallback ( bool bSet )
   bShowVideoAd = bSet;
   return 0;
extern "C" bool AddCoins ( int nCoins )
   //Create an Array using S3D Variables
   S3DX::AIVariable variables[1];
   //Cast the coin value to float from integer
   //Call the actual ShiVa function (AI, Handler, NumOfArgs, ArrayHoldingArgs)
   S3DClient_SendEventToCurrentUser("MainAI", "onAddCoins", 1, &variables);
   return 0;

– Go up higher again and add another function as follows:

void onShowVideoAdCallback ( unsigned char _iArgumentCount, const void *_pArguments, void *_pUserData )
   if ( _pArguments && ( _iArgumentCount == 1 ) )
      const S3DX::AIVariable *pVariables = (const S3DX::AIVariable *)_pArguments ;
      if ( pVariables[0].GetType ( ) == S3DX::AIVariable::eTypeBoolean )
         bShowVideoAd = pVariables[0].GetBooleanValue ( ) ;

– Go down to approx line 410 and add the following function:

extern "C" bool S3DEngine_ShowVideoAd ( )
   return bShowVideoAd ;

– Save the file. Open S3DEngine_Wrapper.h. Go down to the bottom and add the following lines (approx. line 40):

 extern bool S3DEngine_ShowVideoAd ( );
 extern bool SetShowVideoAdCallback ( );
 extern bool AddCoins ( );

– Save the file Open S3DEngine_AppDelegate.h and add the following to the Import section:

 #import "AdColonyPublic.h"

– At approx. line 12 where it says @interface S3DEngine_AppDelegate : NSObject, we want to add the AdColonyDelegate and AdColonyTakeoverAdDelegate commands in the tag. The function now looks as follows:

@interface S3DEngine_AppDelegate : NSObject 
   //Do not change any of the code in here...

– Ad this code to the Import section in S3DEngine_AppDelegate.m (approx. line 7):

 #import "AdColonyPublic.h"

– Add the following setup code in the applicationDidFinishLaunching function at the bottom (approx. line 85 after the [viewController.glView playDefaultMovieIfAny];) :

 //AdColony Setup Code
 [AdColony initAdColonyWithDelegate:self];

– Below that function just outside, add the following 3 functions. Replace the AdColony App ID and Zone IDs with your own:

// Provide the AdColony app ID for your application
// This can be retrieved from your account on
-(NSString *)adColonyApplicationID
    return @"AD_COLONY_APP_ID"; // AdColony app ID
// Provide a dictionary of AdColony zone IDs for all zones in use throughout the app.
// These can be retrieved from your account on
// Slot numbers are arbitrary integers
-(NSDictionary *)adColonyAdZoneNumberAssociation
    // Enter zone ID or Slot number below
    return [NSDictionary dictionaryWithObjectsAndKeys:
            @"AD_COLONY_ZONE_ID_OR_SLOT_NUMBER", [NSNumber numberWithInt:1], nil];
// Enable helpful console log messages
-(NSString *)adColonyLoggingStatus
    return AdColonyLoggingOn;

At this point, the ad video will take some time to download from the servers and will NOT DISPLAY until fully downloaded. For this reason, it is best to run the command to show video later in your app. In V4VC, we are specifically going to run the command based on a button click and reward users coins in our app.
– Open S3DEngine_EAGLView.h and add the following import code to the top (approx. Line 12):

 #import "AdColonyPublic.h"

– Go down to the @interface part (approx. line 20) and replace the line with the following:

 // before:
 @interface S3DEngine_EAGLView : UIView 
 // after:
 @interface S3DEngine_EAGLView : UIView 

– Save and open S3DEngine_EAGLView.m. At the top in the imports section, add the following (approx. line 10):

 #import "AdColonyPublic.h"

– Go down to the drawView function (approx. line 260). Add the following if statement (approx line 360) and replace the ZONE ID with your own:

   if ( S3DEngine_ShowVideoAd ( ) )
      //Play AdColony Video Basic NON-V4VC
      //[AdColony playVideoAdForZone:@"AD_COLONY_ZONE_OR_SLOT_ID_HERE"];
      //Play AdColony Video V4VC POST-POPUP
      [AdColony playVideoAdForZone:@"AD_COLONY_ZONE_OR_SLOT_ID_HERE" withDelegate:self withV4VCPrePopup:NO withV4VCPostPopup:YES];
      SetShowVideoAdCallback ( false ) ;

V4VC Rewards

– Go back to the AdColony website and click on your app.
– Go down to Ad Zones and select the first Ad Zone. Edit and enable Virtual Currency Rewards.
– Set Client Side Only to YES unless you are planning on using the Server.
“In order to use V4VC™ your application needs “currency” or virtual goods or something to reward your users in exchange for completed video views. To use the server verification system for V4VC™ transaction, you must have a server API (or script) that can increment your user’s virtual currency balances via the url callback, referred to as a server-side solution. If you manage your user’s virtual currency on the client, referred to as client-side solution, then you will need to reward your users via code in your app when notified by the AdColony SDK.” Source:
Ignore the Callback URL for now unless you have selected Server Side Integration. In the Virtual Currency Name, enter the name you call your coins in the game. You may call them Diamonds, Gears, Gems, etc. The Daily max per user should reflect the number of times you want a user to be able to receive rewards per day. The Reward Amount per completed view should reflect the amount you wish to reward the user. If the virtual currency that you use with V4VC is more valuable than the typical revenue generated from an AdColony video, then you should supply a value for the Videos Needed per Reward field that is greater than 1.

Post-Popup Experience

– Open S3DEngine_AppDelegate.m. Go down to the AdColony Functions and add the following one below them (approx. line 113):

-(void)adColonyVirtualCurrencyAwardedByZone:(NSString *)zone currencyName:(NSString *)name
currencyAmount:(int)amount {
   //Update virtual currency balance by contacting the game server here
   //NOTE: The currency award transaction will be complete at this point
   //NOTE: This callback can be executed by AdColony at any time
   //NOTE: This is the ideal place for an alert about the successful reward
   // This function will return the total award coins to your ShiVa code
   AddCoins ( amount );

– Save, compile and run your app. Your users should now be able to get coins or virtual currency in your game or app simply by watching a video!

Need more answers?

  • slackBanner