Integrate your iOS App with Listrak platform to send Mobile App Push Notifications. There are three steps: 💡 Before you begin, work with your Account Manager to gain access to Push Channel in your Listrak account.
Follow these 4 steps to complete the Android App Integration:
STEP 1: Create the Listrak Integration
Navigate to Integrations > Integrations Integration Management.
Click on New Integration.
Select the Mobile App API card and click Integrate.
Click Setup Integration.
Give the integration a name.
Select the Mobile App
Save a new integration and copy the Client ID and Client Secret for later use in the integration steps.
⚠️ This step only needs to be done once, so if this was completed during the Android App Integration process, move to the next step.
STEP 2: Add SDK as a dependency to iOS App using Carthage
For reference, you can find the SDK hosted here/on github
If your project does not already have a Cartfile, create it in your project directory
Add the following line to the Cartfile, for the version of the SDK you are using; for example, to use exactly version 1.0.0 you would add:
binary "https://raw.githubusercontent.com/listrak/Listrak-iOS-SDK/master/ListrakSDK-iOS.json" == 1.0.0
4. Run carthage update
5. Go to the general settings for your project, Frameworks, Libraries, and Embedded Content section either drag and drop the .framework folder from Carthage/Build/iOS here, or use the plus icon to locate it
STEP 3: Integrate SDK
INITIALIZE THE SDK
1. In AppDelegate.m create a static variable for the ListrakClient; import "ListrakSDK-iOS/bindings.h"
AppDelegate.m
static ListrakClient *client;
2. In the didFinishLaunchingWithOptions
method of AppDelegate.m initialize the
ListrakClient passing in your clientID and clientSecret
client = [[ListrakClientalloc] initWithClientID:@"clientID"clientSecret:@"clientSecret"];
3. Add a getter method for the ListrakClient so you can access it throughout your app; import "ListrakSDK-iOS/bindings.h"
in AppDelegate.h
AppDelegate.h
+ (ListrakClient*)getListrakClient;
AppDelegate.m
+ (ListrakClient*)getListrakClient{ return client; }
4. If bitcode is enabled your your project, you will need to disable it; this setting can be found in your project settings Build Settings > Build Options > Enable Bitcode
SET UP EVENT TRACKING
1. In applicationDidBecomeActive
in AppDelegate.m, call the onEnterForeground
method of the client - this tracks an app open
AppDelegate.m
[client onEnterForeground];
2. In applicationWillResignActive
in AppDelegate.m, call the onEnterBackground
method of the client - this tracks an app close
AppDelegate.m
[client onEnterBackground];
PROFILE FIELDS
The setProfileFields
method accepts - Email, First Name, Last Name, Phone Number, Birthday, and Postal Code. The first parameter of this method is the SegmentationAction enum
, which can be accessed with Enums_SegmentationActionUpdate
or Enums_SegmentationActionOverwrite
(note that you will need to import "ListrakSDK-iOS/bindings.h"
).
Update will update all the fields that have values and leave the existing value for any field that you passed over as null
Overwrite will set all the fields to the values you passed over, so if there was data for a field previously, but you pass over null for that field, it will now be set to null
If you don't wish to include the phone number, you must set it to 0 instead of null
Phone Number is of type Long, all the rest are of type NSString
Birthday is expected to be a string with the format MM/DD/YYYY or MM-DD-YYYY
TIP: You may need to use the getter method set up in Step 2, Initialize the SDK, #6 to access the ListrakClient
Some examples are:
[[AppDelegate getListrakClient]
setProfileFieldsSegmentationAction:Enums_SegmentationActionUpdate
email:emailField firstName: firstNameField lastName:lastNameField
phoneNumber:phoneNumberField birthday:birthdayField
postalCode:postalCodeField];
[[AppDelegate getListrakClient]
setProfileFieldsSegmentationAction:Enums_SegmentationActionOverwrite
email:emailField firstName: firstNameField lastName:lastNameField
phoneNumber:0 birthday:nil postalCode:nil];
To verify that Listrak is receiving data, you can install and open the app and the Total App Installs should increase on the Home Dashboard.
SETUP APNS/PUSH NOTIFICATIONS
NOTE: You must be enrolled in the apple developer program in order to use APNS
1. Navigate to the settings for your project
2. Go to Capabilities
3. Enable Push Notifications

4. Enable Background Modes and check Background fetch and Remote notifications

5. Request permission for your app to send push notifications
NOTE: The registerForRemoteNotifications
method must be called from the main thread only; below is an example (you may need to import UserNotifications):
UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
[center requestAuthorizationWithOptions:(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge)
completionHandler:^(BOOL granted, NSError * _Nullable error){
if(!error){
dispatch_async(dispatch_get_main_queue(), ^{
[[UIApplication sharedApplication] registerForRemoteNotifications];
});
}
}
];
6. Add the didRegisterForRemoteNotificationsWithDeviceToken
method to your
AppDelegate if it doesn't already exist. In this method, pass the token (as a string) to Listrak; below is an example:
- (void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)token {
NSString *tokenString = [AppDelegate hexadecimalStringFromData:token];
[client registerDeviceDeviceToken:tokenString];
}
+ (NSString *)hexadecimalStringFromData:(NSData *)data {
NSUInteger dataLength = data.length;
if (dataLength == 0) {
return nil;
}
const unsigned char *dataBuffer = (const unsigned char *)data.bytes;
NSMutableString *hexString = [NSMutableString stringWithCapacity:(dataLength * 2)];
for (int i = 0; i < dataLength; ++i) {
[hexString appendFormat:@"%02x", dataBuffer[i]];
}
return [hexString copy];
}
7. This is how your AppDelegate.m might look now:
AppDelegate.m
#import "AppDelegate.h"
#import "ListrakSDK-iOS/bindings.h"
@import UserNotifications;
@interface AppDelegate ()
@end
@implementation AppDelegate
static ListrakClient *client;
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//Initialize ListrakSDK
client = [[ListrakClient alloc] initWithClientID:@"client-ID" clientSecret:@"client-secret"];
//Ask for permission to send push notifications
UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
[center requestAuthorizationWithOptions:(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge)
completionHandler:^(BOOL granted, NSError * _Nullable error){
if(!error){
dispatch_async(dispatch_get_main_queue(), ^{
[[UIApplication sharedApplication] registerForRemoteNotifications];
});
}
}];
return YES;
}
- (void)applicationWillResignActive:(UIApplication *)application {
//Send background event to Listrak
[client onEnterBackground];
}
- (void)applicationDidBecomeActive:(UIApplication *)application {
// Send foreground event to Listrak
[client onEnterForeground];
}
- (void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)token {
NSString *tokenString = [AppDelegate hexadecimalStringFromData:token];
[client registerDeviceDeviceToken:tokenString];
}
- (void)application:(UIApplication *)app didFailToRegisterForRemoteNotificationsWithError:(NSError *)err {
NSString *str = [NSString stringWithFormat: @"Error: %@", err];
NSLog(@"Error %@",err);
}
+ (ListrakClient*)getListrakClient{
return client;
}
+ (NSString *)hexadecimalStringFromData:(NSData *)data {
NSUInteger dataLength = data.length;
if (dataLength == 0) {
return nil;
}
const unsigned char *dataBuffer = (const unsigned char *)data.bytes;
NSMutableString *hexString = [NSMutableString stringWithCapacity:(dataLength * 2)];
for (int i = 0; i < dataLength; ++i) {
[hexString appendFormat:@"%02x", dataBuffer[i]];
}
return [hexString copy];
}
@end
SETUP CONVERSION TRACKING
In order for Listrak to track purchases made within the app, you will need to pass all the available data about the purchase to Listrak. Order Number or Order Total are the only required fields for conversion tracking.
1. Create a ListrakOrder object; you will need to import ListrakSDK-iOS/bindings.h
ListrakOrder *order = [[ListrakOrder alloc] init];
2. Set the OrderNumber and OrderTotal of the order object, along with any additional data you have
order.OrderNumber = @"123456";
order.OrderTotal = @"119.99";
3. To set the ShippingAddress and BillingAddress use the
setShippingAddressFirstName
and setBillingAddressFirstName
methods; use nil
for any fields you don’t have
For example:
[order setShippingAddressFirstName:@"First"
lastName:@"Last"
address1:@"123 Main Street"
address2:nil
address3:nil
city:@"Lititz"
state:@"PA"
zipCode:@"12345"
country:@"USA"
phone:@"1123456789"];
4. For every item in the order, add the item to the order with the addItemOrderNumber
method; for any fields you don’t have, use nil
if it is a string value and 0
if it is a numeric value
For example:
[order addItemOrderNumber:self.orderNumber
sku:@"ABC-123"
price:12.99
discountedPrice:0
discountType:0
discountDescription:nil
quantity:2
itemTotal:25.98
status:Enums_StatusProcessing
shippingMethod:@"FedEx"
shipDate:@"10-09-2018"
trackingNumber:@"123456"
meta1:nil
meta2:nil
meta3:nil
meta4:nil
meta5:nil];
5. When you have set all the data about the order, submit it to Listrak using the
submitOrder
method
[order submitOrder];
6. To verify that Listrak is receiving your order data, note that you will need to click on a push notification and then place the order; the conversion information will appear on the broadcast report page for the push notification
Below is a list of all the available properties and parameters on the objects and methods:
ListrakOrder
Properties
OrderNumber- NSString
OrderTotal- double
Email- String
CustomerNumber- NSString
HandlingTotal- double
DiscountDescription- NSString
DiscountTotal- double
DiscountType- int **
**Values are available in the Enums class, prefixed with Enums_DiscountType
TaxTotal- double
CouponCode- NSString
Status- int **
**Values are available in the Enums class, prefixed with Enums_Status
ShippingMethod- NSString
ShippingTotal- double
ShipDate- NSString **
**Expected format is MM/DD/YYYY or MM-DD-YYYY
TrackingNumber- NSString
ItemTotal- double
StoreNumber- NSString
AssociateID- NSString
Meta1- NSString
Meta2- NSString
Meta3- NSString
Meta4- NSString
Meta5- NSString
Methods (parameters are listed)
setShippingAddressFirstName
setBillingAddressFirstName
FirstName- NSString
LastName- NSString
Address1- NSString
Address2- NSString
Address3- NSString
City- NSString
State- NSString
ZipCode- NSString
Country- NSString
Phone- NSString
addItemOrderNumber
OrderNumber- NSString
SKU- NSString
Price- double
DiscountedPrice- double
DiscountType- int **
**Values are available in the Enums class, prefixed with Enums_DiscountType
Quantity- int
ItemTotal- double
Status- int **
**Values are available in the Enums class, prefixed with Enums_Status
ShippingMethod- NSString
ShipDate- String **
**Expected format MM/DD/YYYY or MM-DD-YYYY
TrackingNumber- NSString
Meta1- NSString
Meta2- NSString
Meta3- NSString
Meta4- NSString
Meta5- NSString
submitOrder
Enums- DiscountType
Enums_DiscountTypeNotSet()
Enums_DiscountTypePriceOverride()
Enums_DiscountTypePriceRule()
Enums_DiscountTypePromotion()
Enums_DiscountTypeSeniorCitizen()
Enums_DiscountTypeMarkdown()
Enums_DiscountTypeCoupon()
Enums_DiscountTypeQuantityDiscount()
Enums_DiscountTypeRebate()
Enums_DiscountTypeCashDiscount()
Enums_DiscountTypeTradeDiscount()
Enums_DiscountTypeTradeInKind()
Enums_DiscountTypePromptPaymentDiscount()
Enums_DiscountTypeGeneralDiscount()
Enums- Status
Enums_StatusNotSet()
Enums_StatusMisc()
Enums_StatusPreOrder()
Enums_StatusBackOrder()
Enums_StatusPending()
Enums_StatusHold()
Enums_StatusProcessing()
Enums_StatusShipped()
Enums_StatusCompleted()
Enums_StatusReturned()
Enums_StatusCanceled()
Enums_StatusUnknown()
Enums_StatusClosed()
STEP 4: Add iOS Certificate to Listrak
Follow the below steps to set up an iOS push certificate - this certificate authenticates you with Apple to deliver push notifications.
CREATE THE CERTIFICATE
1. Navigate to the iOS Provisioning Panel
2. Navigate to Identifiers on the left-hand side
3. Click App IDs

4. Select an Application
5. Click Edit to update the app settings
6. Enable push notifications

7. Check the enable checkbox
8. Navigate to the Production SSL Certificate
9. Click Create Certificate

10. Follow the SSL certificate instructions
11. After complete, a green status indicates that push is enabled
EXPORT THE CERTIFICATE
1. Navigate to Applications
2. Go to Utilities
3. Then Keychain Access

4. Download the certificate that was previously created
5. Export the certificate as a .p12 file
ADD THE CERTIFICATE TO LISTRAK
Log into Listrak; access the Push Settings by following the below steps:
Navigate to Settings > App Push Settings App Push Settings
Then Settings
Drag and drop the iOS push certificate to complete the integration.
⚠️ All settings for push notifications are disabled until a iOS certificate and Android token is setup.
For more information on Mobile App Push Notifications, reach out to your Account Manager or Listrak Support!