iOS SDK Integration
Swift & Objective-C
Before you start: ByteBrew supports iOS version 9.0 and above. ByteBrew SDK is compatible with iOS 14 updates.
1: Import ByteBrew iOS Library
We have 2 ways to import ByteBrew:
1. Using a Static Library Add the Static Library, "libByteBrewNativeiOSPlugin.a" and "ByteBrewNativeiOSPlugin.h" should be added to your project
To import the library files go to File -> Add Files to "project" and select the two files needed, "libByteBrewNativeiOSPlugin.a" and "ByteBrewNativeiOSPlugin.h".
Make sure to add the library to your project in your targets general settings.
2. Using a XCFramework (recommended) (Swift compatible) Import the ByteBrew.xcframework
To import the framework go to your target -> click the + button on Frameworks, Libraries, and Embeded Content. Locate the ByteBrew.xcframework in your file system
Important: Initialize ByteBrew in your AppDelegate. ByteBrew SDK does not support offline event caching.
2: Go to your ByteBrew Dashboard
Go to your game settings on the ByteBrew dashboard and find your game keys listed on the dashboard.
3: Input game keys
Inside your code, start initializing ByteBrew and have the Game ID and Game Key on hand.
4: Initialize ByteBrew
You must initialize ByteBrew using the code below in the "didFinishLaunchingWithOptions" method AppDelegate of your app or game.
/**OBJECTIVE-C**/
#import "ByteBrewNativeiOSPlugin.h"
//...
//Get the App version
NSString *version = [[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleShortVersionString"];
// Initialize ByteBrew
[ByteBrewNativeiOSPlugin InitializeWithSettings:@"GAME_ID" SecretKey:@"GAME_KEY" EngineVersion:@"iOS Native or whatever you want to put here" BuildVersion:version];
/**SWIFT**/
import ByteBrewNativeiOSPlugin
//...
//Get the App version
let version = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as! String
// Initialize ByteBrew
ByteBrewNativeiOSPlugin.initialize(withSettings: "GAME_ID", secretKey: "GAME_KEY", engineVersion: "SWIFT", buildVersion: version)
Push Notifications
Important: If you are using ByteBrew for Push Notifications, you must call InitializeWithSettings before calling StartPushNotifications.
1: Integrate Push Notifications
Integrating Push Notifications with ByteBrew is super simple. Just add this line of code after the InitializeWithSettings line.
/**OBJECTIVE-C**/
[ByteBrewNativeiOSPlugin StartPushNotification];
/**SWIFT**/
ByteBrewNativeiOSPlugin.startPushNotification()
2: Create Push Notification App on the Dashboard
Set up a Push Notification App in the Push Notification Dashboard. Find the documentation on setting up push notification apps on the Push Notification Documentation Page.
Push Notification Xcode
1: Add UserNotifications.framework
Add UserNotifications.framework to the frameworks and libraries in Xcode.
2: Add Capabilities
Press "+ Capability" and add the following capabilities
3: Add "Background Modes" and check "Remote Notifications"
4: Add "Push Notifications"
Tracking Purchases
To track a basic in-app purchase event utilize the below method.
/**OBJECTIVE-C**/
[ByteBrewNativeiOSPlugin AddTrackedInAppPurchaseEvent:@"Apple App Store" Currency:@"USD" Amount:5.99 ItemID:@"currencyPack01" Category:@"Currencies"];
/**SWIFT**/
ByteBrewNativeiOSPlugin.addTracked(inAppPurchaseEvent: store, currency: currency, amount: amount, itemID: itemID, category: category)
Validate Purchases and Track (Validation Callback)
This will also Track the Purchase. Do not track the purchase after validation callback is received or else it will double the purchases tracked.
To validate and track the in-app purchase as well return info utilize this method. This will create a purchase code block that will return a payload with purchase details and verification status.
Important: Make sure the receipts have correct JSON string formatting.
/**OBJECTIVE-C**/
[ByteBrewNativeiOSPlugin ValidateiOSInAppPurchaseEvent:@"Apple App Store" Currency:@"USD" Amount:5.99 ItemID:@"currencyPack01" Category:@"Currencies" Receipt:@"RECEIPT/PAYLOAD RECIEVED FROM FINALIZED PURCHASES"
finishedValidationResult:^(NSMutableDictionary *purchaseResult) {
//make sure to convert to BOOL, NSDictionary stores BOOL as a NSNumber
NSLog(@"ByteBrew Purchase Processed: %@", [purchaseResult valueForKey:@"purchaseProcessed"]); //Boolean telling if the purchase even went to the server to get checked
//make sure to convert to BOOL, NSDictionary stores BOOL as a NSNumber
NSLog(@"ByteBrew Purchase isValid: %@", [purchaseResult valueForKey:@"isValid"]); //BOOL signaling if the purchase is real or fake
NSLog(@"ByteBrew Purchase itemID: %@", [purchaseResult valueForKey:@"itemID"]); //Product/Item ID of the purchase processed
NSLog(@"ByteBrew Purchase message: %@", [purchaseResult valueForKey:@"message"]); //Message from the server telling the explaination behind the decision
NSLog(@"ByteBrew Purchase timestamp: %@", [purchaseResult valueForKey:@"timestamp"]); //Timestamp from the server telling when the verification occured
}];
/**SWIFT**/
ByteBrewNativeiOSPlugin.validateiOS(inAppPurchaseEvent: store, currency: currency, amount: 0, itemID: itemID, category: category, receipt: receipt) { purchaseResult in
}
The Returned Results:
purchaseProcessed. Boolean saying if the purchase was processed by server.
isValid. Boolean telling if the purchase is Real or Fake
The Returned Result message, will give you an output of either of these as an explaination:
A. "Validation Successful, real purchase."
B. "Validation Failed, fake purchase."
C. "Error validating receipt, check game configs."
If you get Option C, check to make sure the purchaseProcessed boolean is True and to go to your game settings on ByteBrew to update your Apple App Shared Secret.
Track purchase with extra receipt validation (No Callback)
To track the in-app purchase and basic receipt validation utilize the specific platform method.
Important: Make sure the receipts have correct JSON string formatting.
/**OBJECTIVE-C**/
[ByteBrewNativeiOSPlugin AddTrackediOSInAppPurchaseEvent:@"Apple App Store" Currency:@"USD" Amount:5.99 ItemID:@"currencyPack01" Category:@"Currencies" Receipt:@"RECEIPT/PAYLOAD RECIEVED FROM FINALIZED PURCHASES"];
/**SWIFT**/
ByteBrewNativeiOSPlugin.addTrackediOS(inAppPurchaseEvent: "Apple App Store", currency: "USD", amount: 5.99, itemID: "currencyPack01", category: "Currencies", receipt: "RECEIPT/PAYLOAD RECIEVED FROM FINALIZED PURCHASES")
Custom User Data Attributes
Add data attributes to your users such as: level, username, etc. These can be directly used for segmentation purposes in push notifications and more.
/**OBJECTIVE-C**/
[ByteBrewNativeiOSPlugin AddCustomDataAttributeWithStringValue:@"username" Value:@"michael_scarn"];
[ByteBrewNativeiOSPlugin AddCustomDataAttributeWithDoubleValue:@"total_hitpoints" Value:68.7];
[ByteBrewNativeiOSPlugin AddCustomDataAttributeWithIntegerValue:@"dundees" Value:3];
[ByteBrewNativeiOSPlugin AddCustomDataAttributeWithBooleanValue:@"loves_the_office" Value:YES];
/**SWIFT**/
ByteBrewNativeiOSPlugin.addCustomDataAttribute(withStringValue: "username", value: "michael_scarn")
ByteBrewNativeiOSPlugin.addCustomDataAttribute(withStringValue: "total_hitpoints", value: 68.7)
ByteBrewNativeiOSPlugin.addCustomDataAttribute(withStringValue: "dundees", value: 3)
ByteBrewNativeiOSPlugin.addCustomDataAttribute(withStringValue: "loves_the_office", value: true)
Custom Event Tracking
For the most basic form of custom event tracking, use the follow code line. This will track the event name and default the value to 1.
/**OBJECTIVE-C**/
[ByteBrewNativeiOSPlugin AddNewCustomEvent:@"some_event"];
[ByteBrewNativeiOSPlugin AddNewCustomEventWithStringValue:@"CustomEventName" Value:@"Key=Value;"];
/**SWIFT**/
ByteBrewNativeiOSPlugin.addNewCustomEvent("some_event")
ByteBrewNativeiOSPlugin.addNewCustomEvent(withStringValue: "CustomEventName", value: "Key=Value;")
Basic value parameter custom event
To add more detail to an event you can add a secondary parameter, that can be a float or string value.
/**OBJECTIVE-C**/
//string example
[ByteBrewNativeiOSPlugin AddNewCustomEventWithStringValue:@"some_event" Value:@"someValue"];
//Numeric example
[ByteBrewNativeiOSPlugin AddNewCustomEventWithNumericValue:@"some_event" Value:5];
/**SWIFT**/
//string example
ByteBrewNativeiOSPlugin.addNewCustomEvent(withStringValue: "some_event", value: "someValue")
//Numeric example
ByteBrewNativeiOSPlugin.addNewCustomEvent(withNumericValue: "some_event", value: 5)
Dictionary parameter custom event
To add additional custom parameters to an event you can format a string with key=value; pairs. Checkout the example below.
/**OBJECTIVE-C**/
//Key Value format "key=value;"
//It can take multiple pairs as well, "key1=pair1;key2=pair2;key3=pair3;"
[ByteBrewNativeiOSPlugin AddNewCustomEventWithStringValue:@"level_started" Value:@"weapon=megablaster;powerup=extralife;"];
/**SWIFT**/
//Key Value format "key=value;"
//It can take multiple pairs as well, "key1=pair1;key2=pair2;key3=pair3;"
ByteBrewNativeiOSPlugin.addNewCustomEvent(withStringValue: "level_started", value: "weapon=megablaster;powerup=extralife;")
Progression Event Tracking
You can track a progression event using the parameters list below.
Progression events get tracked based on the following parameters:
1: ProgressionType
The type of event context that occured. Must use one of the following: Started, Completed or Failed
2: Environment
Area of the game or World it occurs (Ex. Tutorial, Arena, Level)
3: Stage
The stage of the environment (Ex. kings_arena, jungleLevel, level_02)
4: Value
This can be a string or float value attached to the event
/**OBJECTIVE-C**/
//Example Progression event where the user started a tutorial in arena 0 or first arena
[ByteBrewNativeiOSPlugin AddProgressionEvent:Started Environment:@"Tutorial" Stage:@"arena0"];
//Example progression event where the user has completed the kings arena and could be rewarded with 3 crowns
[ByteBrewNativeiOSPlugin AddProgressionEventWithNumericValue:Completed Environment:@"Arena" Stage:@"kings_arena" Value:3];
/**SWIFT**/
//Example Progression event where the user started a tutorial in arena 0 or first arena
ByteBrewNativeiOSPlugin.addProgressionEvent(Started, environment: "Tutorial", stage: "arena0")
//Example progression event where the user has completed the kings arena and could be rewarded with 3 crowns
ByteBrewNativeiOSPlugin.addProgressionEvent(withNumericValue: Completed, environment: "Arena", stage: "kings_arena", value: 3)
Ad Event Tracking
Track ad events that occur to get more detailed breakdowns in your monetization, especially when doing LTV and ROAS calculations.
/**OBJECTIVE-C**/
// Record the Placement Type, Location of the placement, ad unit ID, and Network
[ByteBrewNativeiOSPlugin NewTrackedAdEvent:@"Interstitial" AdLocation:@"EndOfLevel" AdID:@"3253k3302-3r3j4i343-3nij343-405403" AdProvider:@"AdMob"];
//Some ad event paramters can be ommited like so
[ByteBrewNativeiOSPlugin NewTrackedAdEvent:@"Interstitial" AdLocation:@"EndOfLevel"];
[ByteBrewNativeiOSPlugin NewTrackedAdEvent:@"Interstitial" AdLocation:@"EndOfLevel" AdID:@"3253k3302-3r3j4i343-3nij343-405403"];
/**SWIFT**/
// Record the Placement Type, Location of the placement, ad unit ID, and Network
ByteBrewNativeiOSPlugin.newTrackedAdEvent("Banner", adLocation: "EndOfLevel", adID: "3253k3302-3r3j4i343-3nij343-405403", adProvider: "AdMob")
//Some ad event paramters can be ommited like so
ByteBrewNativeiOSPlugin.newTrackedAdEvent("Interstitial", adLocation: "EndOfLevel")
ByteBrewNativeiOSPlugin.newTrackedAdEvent("Reward", adLocation: "EndOfLevel", adID: "3253k3302-3r3j4i343-3nij343-405403")
Remote Config & AB Testing
Remote configs help you edit your apps settings and configuration without needed to update your app on the store.
AB Testing is to cross track changes across a variety of users when they onboard to your game, we distribute AB Test variables from remote configs. So make sure to check for the AB test you are tracking
1: Loading the Remote Configs
When using Remote Config you must first call for the config to get updated. You can call this whenever you want to update the configs.
/**OBJECTIVE-C**/
//Call the handler
[ByteBrewNativeiOSPlugin LoadRemoteConfigs:^(BOOl status) {
//Do whatever you want to do, call a method to get the value?
}];
//Check if the remote configs are ready and set
BOOL ready = [ByteBrewNativeiOSPlugin HasRemoteConfigs];
/**SWIFT**/
//Call the handler
ByteBrewNativeiOSPlugin.loadRemoteConfigs { finished in
}
//Check if the remote configs are ready and set
Bool ready = ByteBrewNativeiOSPlugin.hasRemoteConfigs()
2: Retrieve the Config
Finally once the completion block has finished, you can call the remote config method below.
You can grab AB Test keys and values from this method as well, if the user is part of the control group it wont return anything but the default parameter value set.
/**OBJECTIVE-C**/
//Call to get the key specific value and if the key doesn't exist it will return the default variable specified, like if the AB test user is in the control group
NSString *value = [ByteBrewNativeiOSPlugin RetrieveRemoteConfigs:@"dailyWeapon" DefaultValue:@"goldRevolver"];
/**SWIFT**/
//Call to get the key specific value and if the key doesn't exist it will return the default variable specified, like if the AB test user is in the control group
var config_value = ByteBrewNativeiOSPlugin.retrieveRemoteConfigs("config_key", defaultValue: "default_val")
To view your game's remote configs visit the remote config page on the ByteBrew dashboard.
Get User ID
Get the current userID of the user, use this to find specific user for ex. Push Notifications.
/**OBJECTIVE-C**/
// Get the string userID
NSString* userID = [ByteBrewNativeiOSPlugin GetUserID];
/**SWIFT**/
// Get the string userID
var user_id = ByteBrewNativeiOSPlugin.getUserID()
Stop Tracking Current User
Call the ByteBrew StopTracking method to stop and disable tracking for a user. Alternatively, if you have your own consent prompt, you can delay the intialization of the ByteBrew SDK until your user has consented to be tracked.
/**OBJECTIVE-C**/
[ByteBrewNativeiOSPlugin StopTracking];
/**SWIFT**/
ByteBrewNativeiOSPlugin.stopTracking()