iOS App Integration

Integrate your iOS App with Listrak platform to send Mobile App Push Notifications. There are three steps: Step 1. Add the SDK as a dependency to App, Step 2. Integrate SDK, Step 3. Add iOS Certificate to Listrak. Continue to walk through the steps below to begin.

NOTE: Before you begin, work with your Account Manager to gain access to Push Channel in your Listrak account. Set up the Listrak integration by logging in and going to Manage > Integrations > New Integration > Mobile App API > Setup Integration. Save a new integration and copy the Client ID and Client Secret for later use in these integration steps.

STEP 1. Add SDK as a dependency to iOS App using Carthage

For reference, you can find the SDK hosted here/on github

1. If your project does not already have a Cartfile, create it in your project directory
2. 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 2. 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 3. 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:

1. Navigate from the home menu to Manage
2. Then Settings
3. Drag and drop the iOS push certificate

• NOTE: All settings for push notifications are disabled until a iOS certificate and Android token is setup.

The integration is complete.

For more information on Mobile App Push Notifications, reach out to your Account Manager or Listrak Support!