| TestsTested | ✓ |
| LangLanguage | Obj-CObjective C |
| License | Apache 2 |
| ReleasedLast Release | Dec 2014 |
Maintained by Unclaimed.
If you want to deploy your application to multiple platforms (eg: iOS, Android, etc), you'll need to create a separate Playnomics Applications in the control panel. Each application has a separate <APPID> used for tracking and messaging integration.
Supports iOS versions 5+.
You can download the SDK from our releases page, or you can add our SDK to your CocoaPods Podfile with pod "Playnomics".
All of the necessary install files are in the Playnomics folder:
You can also fork this repo, building the PlaynomicsSDK project.
Import the SDK files into your existing app through Xcode.
To start tracking user engagement data, you need to first start a session. No other SDK calls will work until you do this.
In the class that implements AppDelegate, start the PlayRM Session in the didFinishLaunchingWithOptions method.
#import "AppDelegate.h"
#import "Playnomics.h"
@implementation AppDelegate
- (BOOL) application: (UIApplication *) application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
const unsigned long long applicationId = <APPID>;
[Playnomics startWithApplicationId:applicationId];
//other code to initialize your iOS application below this
}You can either provide a dynamic <USER-ID> to identify each user:
+ (BOOL) startWithApplicationId:(unsigned long long) applicationId andUserId: (NSString *) userId;or have PlayRM, generate a best-effort unique-identifier for the user:
+ (BOOL) startWithApplicationId:(unsigned long long) applicationId;If you do choose to provide a <USER-ID>, this value should be persistent, anonymized, and unique to each user. This is typically discerned dynamically when a user starts the application. Some potential implementations:
You cannot use the user's Facebook ID or any personally identifiable information (plain-text email, name, etc) for the <USER-ID>.
To track user intensity, PlayRM needs to know about UI events occurring in the app. We provide an implementation of UIApplication<UIApplicationDelegate>, which automatically captures these events. In the main.m file of your iOS application, you pass this class name into the UIApplicationMain method:
#import <UIKit/UIKit.h>
#import "AppDelegate.h"
#import "Playnomics.h"
int main(int argc, char *argv[])
{
@autoreleasepool {
return UIApplicationMain(argc, argv, NSStringFromClass([PNApplication class]), NSStringFromClass([AppDelegate class]));
}
}If you already have your own implementation of UIApplication<UIApplicationDelegate> in main.m, just add the following code snippet to your class implementation:
#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
#import "Playnomics.h"
@implementation YourApplication
- (void) sendEvent: (UIEvent *) event {
[super sendEvent:event];
[Playnomics onUIEventReceived:event];
}
@endThis guide assumes you're already familiar with the concept of placements and messaging, and that you have all of the relevant placements setup for your application.
If you are new to PlayRM's messaging feature, please refer to integration documentation.
Once you have all of your placements created with their associated <PLACEMENT-ID>s, you can start the integration process.
We recommend that you preload all placements when your application loads, so that you can quickly show a message when necessary:
+ (void) preloadPlacementsWithNames:(NSString *) firstPlacementName, ... NS_REQUIRES_NIL_TERMINATION;//...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[Playnomics startWithApplicationId:applicationId];
//preloads placements at app start
[Playnomics preloadPlacementsWithNames:@"placement 1", @"placement 2", @"placement 3", @"placement 4", nil];
//...
}Then when you're ready, you can show the placement:
+ (void) showPlacementWithName:(NSString *) placementName;| Name | Type | Description |
|---|---|---|
placementName |
NSString* | Unique identifier for a placement |
Optionally, associate a class that can respond to the PlaynomicsPlacementDelegate protocol, to process rich data callbacks. See Using Rich Data Callbacks for more information.
+ (void) showPlacementWithName:(NSString *) placementName
delegate:(id<PlaynomicsPlacementDelegate>) delegate;| Name | Type | Description |
|---|---|---|
placementName |
NSString* | Unique identifier for a placement |
delegate |
id<PlaynomicsPlacementDelegate> | Processes rich data callbacks, see Using Rich Data Callbacks. This delegate is not retained, you are responsible for managing the lifecycle of this object. |
By default, the SDK renders placements on the Root ViewController's view. If your application uses multiple ViewControllers, you need to explicitally set the parent View for the placement by calling:
+ (void) setPlacementParentView:(UIView *) parentView;| Name | Type | Description |
|---|---|---|
parentView |
UIView * | The parent view where the placement should be rendered. |
Do this before, calling showPlacementWithName:
-(void) viewDidLoad {
//Show the placement after the ViewController has been loaded
[Playnomics setPlacementParentView: self.view];
[Playnomics showPlacementWithName:@"placement 1"];
}Using an implementation of PlaynomicsPlacementDelegate your application can receive notifications when a placement:
@protocol PlaynomicsPlacementDelegate <NSObject>
@optional
-(void) onShow: (NSDictionary *) jsonData;
-(void) onTouch: (NSDictionary *) jsonData;
-(void) onClose: (NSDictionary *) jsonData;
-(void) onDidFailToRender;
@endFor each of these events, your delegate may also receive Rich Data that has been tied with this creative. Rich Data is a JSON message that you can associate with your message creative. In all cases, the jsonData value can be nil.
The actual contents of your JSON message can be delayed until the time of the messaging campaign configuration. However, the structure of your message needs to be decided before you can process it in your application. See example use-cases for rich data.
After you've finished the installation, you should verify that your application is correctly integrated by checkout the integration verification section of your application page.
Using iOS SDK v1.4.0+ you can register your device as a Test Device and validate your events on the self-check page for your application: https://controlpanel.playnomics.com/applications/<APPID>
To test your in-app campaigns, you can enter your IDFV (id for vendor) and select which segments to fall into. Optionally, you can opt to not select any segments to simply see your device's data flowing through the validator.
This page will update with events as they occur in real-time, with any errors flagged.
We strongly recommend running the self-check validator before deploying your newly integrated application to production.
PlayRM allows you to track monetization through in-app purchases denominated in real US dollars.
+ (void) transactionWithUSDPrice: (NSNumber *) priceInUSD
quantity: (NSInteger) quantity;| Name | Type | Description |
|---|---|---|
priceInUSD |
NSNumber * | The price of the item in USD. |
quantity |
NSInteger | The number of items being purchased at the price specified. |
NSNumber * priceInUSD = [NSNumber numberWithFloat:0.99];
NSInteger quantity = 1;
[Playnomics transactionWithUSDPrice: priceInUSD quantity: quantity];PlayRM allows you track and segment based on the source of install attribution. You can track this at the level of a source like AdMob or MoPub, and optionally include a campaign and an install date. By default, PlayRM tracks the install date by the first day we started seeing engagement date for your users.
+ (void) attributeInstallToSource:(NSString *) source;
+ (void) attributeInstallToSource:(NSString *) source
withCampaign:(NSString *) campaign;
+ (void) attributeInstallToSource:(NSString *) source
withCampaign:(NSString *) campaign
onInstallDate:(NSDate *) installDate;| Name | Type | Description |
|---|---|---|
source |
NSString * | The source of install. |
campaign |
NSString * | The campaign for this source. |
installDate |
NSDate * | The date this user installed your app. |
[Playnomics attributeInstallToSource:@"AdMob" withCampaign:@"Holiday" onInstallDate:[NSDate date]];Custom Events may be used in a number of ways. They can be used to track certain key in-app events such as finishing a tutorial or receiving a high score. They may also be used to track other important lifecycle events such as level up, zone unlocked, etc. PlayRM, by default, supports up to five custom events. You can then use these custom events to create more targeted custom segments.
Each time a user completes a certain event, track it with this call:
+ (void) customEventWithName: (NSString *) customEventName;| Name | Type | Description |
|---|---|---|
customEventName |
NSString * | A string to indentify the event. |
Example client-side calls for users completing events, with generated IDs:
[Playnomics customEventWithName: @"level 1 complete"];To set up push notifications, please view the wiki page.
If you have any questions or issues, please contact [email protected].
View version tags here