Prerequisites

Before you start to integrate the SDK into your app, you need to register your app and generate its API key on the FollowAnalytics platform, by following the instructions here.

Getting Started

In this section, you will find the basic steps to integrate the SDK into your app:

• Installing the SDK in your project
• Initializing the SDK using your API key
• Setting up notifications

Once the integration is finished, we highly recommend you test the setup. Then, you can start tagging events and saving attributes in your app.

Installation from CocoaPods

1. Add pod 'FollowAnalytics','~> 6.5.4' in the Podfile (see screenshot below)

2. Run pod repo update from the command line. This will enable CocoaPods to detect the latest available version of FollowAnalytics.

3. Run pod install

Now FollowAnalytics is successfully installed.

Manual installation

1. Go to your Xcode project’s General settings of your target, drag and drop the FollowAnalytics.framework in the Embedded Binaries section. Make sure Copy items if needed is selected and click Finish.

   

2. Create a new Run Script Phase in your app’s target Build Phases and paste the following snippet in the script text field:

   bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/FollowAnalytics.framework/strip-frameworks.sh"
   

   This step is required to work around an App Store submission bug when archiving universal binaries.

Initialize the SDK with your API key

1. Import the FollowAnalytics framework in your AppDelegate.

2. Inside your UIApplicationDelegate implementation, create a configuration object and set the required fields

3. Just below the configuration object, start the SDK

Your code should look like this:

#import <FollowAnalytics/FollowAnalytics.h>

@implementation AppDelegate
- (BOOL)application:(UIApplication*)application
  didFinishLaunchingWithOptions:(NSDictionary*)launchOptions {
  // ....
  // as early as possible
  FollowAnalyticsConfiguration* configuration = [FollowAnalyticsConfiguration
    configurationWith:^(FollowAnalyticsConfiguration* _Nonnull config) {
      config.apiKey = @"YOUR API KEY";
      config.isVerbose = true; // Before publishing the app, set isVerbose to false
    }];
  [FollowAnalytics startWithConfiguration:configuration startupOptions:launchOptions];
  //....
}
// ..
@end

import FollowAnalytics

class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication, didFinishLaunchingWithOptions
    launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // ....
    let configuration = FollowAnalyticsConfiguration.init { (config) in
      config.apiKey = "YOUR API KEY"
      config.isVerbose = true // Before publishing the app, set isVerbose to false
    }
    FollowAnalytics.start(with: configuration, startupOptions: launchOptions)
    // ....
  }
}

You can configure the SDK with all the available parameters which you can find here.

Setting up push notifications

To set up push notification, you will need to perform the following steps:

• Generate and import a p12 push certificate or a p8 authentication key to the FollowAnalytics platform.
• Add push notification capabilities to your XCode project.
• Call the notification authorisation request method from your code to prompt the user to allow your app to send notifications.
• Eventually, to validate your app, you will need to enable device registration for sending the device ID to the platform, so you can use the device observer.

Generate and import a p12 push certificate

1. If you don't have a Certificate Signing Request yet, create one by following instructions here.

2. Go to your Apple developer account in the Certificates, Identifiers & Profiles page.

3. Click on the Identifiers tab.

4. If you already have an app Identifier (App ID), click on your App ID, otherwise click on the + button and create a new App ID.

5. In the list of Capabilities, check the Push Notifications box and click on Save.

6. Click on the Certificates tab.

7. Click on the + button to add a new certificate.

8. Select Apple Push Notification service SSL (Sandbox & Production) and click on Continue.

9. Select your App ID in the list and click on Continue.

10. In the file picker, select the previously created Certificate Signing Request from your disk and click on Continue.

11. Click on Download to retrieve the .cer certificate file.

12. Double-click the downloaded certificate, this should open the Keychain Access app.

13. Locate the certificate in Keychain Access under Certificates, right-click on it, select Export Apple Push Services:… and save it as a .p12 file.

14. Enter a password for your certificate.

15. Go to the Administration page of your app on the FollowAnalytics platform.

16. Add the exported .p12 file and click on Proceed.

17. Enter the certificate password and click on Proceed.

Do not forget to ensure your provisioning profile has the Push Notifications service enabled by expanding it from the list in your developer portal.

Generate and import a p8 authentication key

1. Go to your Apple developer account in the Certificates, Identifiers & Profiles page.

2. Click on the Keys tab.

3. Click on the + button to add a new Key.

4. Enter a name in the Key Name field.

5. Check the Apple Push Notification service (APNs)

6. Click on Continue and then on Register.

7. Click on Download to retrieve the .p8 file. Note that once downloaded, you will not be able to download the p8 file again.

8. Get back to the Keys list and click on the Identifiers tab.

9. If you already have an app Identifier (App ID), click on your App ID, otherwise click on the + button and create a new App ID.

10. In the list of Capabilities, check the Push Notifications box and and click on Save.

11. Go to the Administration page of your app on the FollowAnalytics platform.

12. Add the downloaded .p8 file and click on Proceed.

13. Enter your Key ID and Issuer Key. Your Key ID can be found from the Keys tab of the Certificates, Identifiers & Profiles page in the Apple developer account. Your Issuer Key is your team ID, it can be found from the Membership page in the Apple developer account.

Do not forget to ensure your provisioning profile has the Push Notifications service enabled by expanding it from the list in your developer portal.

Push notification capabilities

In the Capabilities tab of your Xcode Project:

1. Enable Push Notifications by setting the switch to ON.

2. Enable the Remote notifications capability in the Background Modes:

   This will ensure that FollowAnalytics can detect uninstalls and send Silent Push Notifications.

Enable quiet notifications

Since iOS 12, Apple introduced a way to receive non-interruptive notifications before the user grants notification authorization. These are notification delivered quietly (no sound, no banner) and that are only displayed in the Notification Center.

You can allow your app to receive quiet notifications from FollowAnalytics as soon as it's installed on the user's device. To do so, just call requestProvisionalNotificationAuthorization in the didFinishLaunchingWithOptions method of your app delegate, after the SDK initialization call.

+ (void)requestProvisionalNotificationAuthorization;

static func requestProvisionalNotificationAuthorization()

Prompt the user to allow notifications

Later in the user experience, you can ask the user to provide its authorization for notifications. You can do this by calling the requestNotificationAuthorisation method at some point:

+ (void)requestNotificationAuthorization;

static func requestNotificationAuthorisation()

If you don't call and user hasn't allowed notifications, your app will only be able to receive silent notifications.

Enable device registration

To allow the user to retrieve the device ID for testing from the platform, declare a URL Scheme in the info tab of your Xcode project using the bundleId of your app as URL Scheme:

1. Go to the info tab of the project targets.

2. At the bottom you select the subsection called "URL Types".

3. Click the + sign at the bottom.

4. Add the bundle ID of your app in both identifier and URL Schemes fields

Once configured, your FollowAnalytics device ID can be obtained by opening the following URI: YourURLScheme://followanalytics.com/deviceId, with YourURLScheme as the application bundle ID.

Now, users can add devices to the FollowAnalytics platform without knowing the device ID. From the platform, they will send an email a link that will open the app and allow them to register the device.

Setting up keychain access group

Keychain is a secure storage suitable for short bits of sensitive information and by default, the data saved in one application can not be read in other applications. To share the Device ID across applications of the same publisher it is required to specify a keychain group name. To configure it, you will need to perform the following steps:

Enable keychain sharing

1. In XCode project settings, select your app target and from the Signing & Capabilities tab click +Capability;
2. From the popup find and select the Keychain Sharing option;
3. Back on the capabilities list of the application add the group name to be used, e.g. keychain.group.name.example.

Setup the group name in the SDK

Set the configuration field .keychainGroupName with the respective publisher Team ID and Group Name joined but a ..

To know your Team ID:

1. Login to your Apple developer account (https://developer.apple.com/account);
2. Select Membership from the left panel;
3. Find the Team ID value from the Membership Information list.

FollowAnalyticsConfiguration* configuration = [FollowAnalyticsConfiguration
    configurationWith:^(FollowAnalyticsConfiguration* _Nonnull config) {
      // ...
      // Replacing the YOUR_TEAM_ID with the respective value.
      config.keychainGroupName = @"YOUR_TEAM_ID.keychain.group.name.example";
      // ...
    }];

  let configuration = FollowAnalyticsConfiguration.init { (config) in
    // ...
    // Replacing the YOUR_TEAM_ID with the respective value.
    config.keychainGroupName = "YOUR_TEAM_ID.keychain.group.name.example"
    // ...
  }
  FollowAnalytics.start(with: configuration, startupOptions: launchOptions)

Analytics

To enrich User Analytics on the platform, FollowAnalytics SDK allows you to:

• Log your users events, errors and locations.
• Set attributes for your users.

Logs and attributes can also be used to target specific audiences when creating campaigns on the platform. You can find more information about the difference between logs and attributes here.

Our CSM team can help you creating relevant logs in your app. You can also find our recommendations here.

Logging Events and Errors

You can log Events and Errors in your app by calling the following methods:

+ (void)logEvent:(nonnull NSString*)name details:(nullable id)details;
+ (void)logError:(nonnull NSString*)name details:(nullable id)details;

static func logEvent(name: String, details: Any?)
static func logError(name: String, details: Any?)

Those methods print the log description in the console and also print an information about the log validity.

Use name as a unique identifier for your log. Use details to pass specific context to your log.

If details exceeds 60KB it will be considered as invalid. Additionally, to be valid, details must be one of the following:

• A nil value
• A String
• A Dictionary representing a valid flat JSON object (i.e. that doesn't contain any nested Dictionary or Array field).

Passing any invalid details to those methods will:

• Print an error in the console
• Ignore the details argument and send the log with no details

The following code shows an example of how you can log the viewing and the purchasing of a product:

[FollowAnalytics logEvent:@"Product view" details:@"RF1672"];

NSDictionary *details = @{@"reference": @"RF1672",
                          @"payment_mode" : @"credit_card",
                          @"color" : @"red"};
[FollowAnalytics logEvent:@"Product purchased" details:details];

FollowAnalytics.logEvent("Product view", details: "RF1672")

let details = ["reference": "RF1672",
               "payment_mode": "credit_card",
               "color": "red"]
FollowAnalytics.logEvent("Product purchased", details: details)

Logging Locations

There are two ways for logging locations:

+ (void)logLocationWithLatitude:(double)latitude longitude:(double)longitude;
+ (void)logLocation:(nonnull CLLocation*)location;

static func logLocation(withLatitude: Double, longitude: Double)
static func logLocation(location: CLLocation)

Those methods print the log description in the console and also print an information about the log validity:

• if the location distance from the last logged location is less than 100 meters, the log will be ignored.
• if the location time interval from the last logged location is less that 1 hour, the log will be ignored.

One way to use the logLocation method, is to implement the didUpdateLocations method of the CLLocationManagerDelegate to log the last location update. FollowAnalytics SDK will take care of ignoring a location log if this location is too close from the last one:

func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
  if let location = locations.last {
    FollowAnalytics.logLocation(location)
  }
}

User Attributes

A user can be defined by setting its identifier. This identifier is a string that you provide to the SDK to uniquely identify a user of your app. It can be an e-mail address, an identifier from your own backend (for instance a primary key), a phone number, or anything else that could allow you to uniquely identify a user.

Attributes (like first name, date of birth...) can be associated to a user if it's defined. Attributes are associated to the device when no user is defined.

When a user is defined, a user profile is created server-side and can be shared across apps.

You can set predefined as well as custom attributes.

Define a user

To define a user, set its user ID:

FollowAnalytics.setUserId("UniqueIdentifier")

To remove a user (for example in case of a sign out), just pass nil to setUserId:

FollowAnalytics.setUserId(nil)

Predefined attributes

To set predefined attributes, you can call the following methods on the userAttributes property provided by the SDK:

- (void)setFirstName:(nullable NSString*)firstName;
- (void)setLastName:(nullable NSString*)lastName;
- (void)setEmail:(nullable NSString*)email;
- (void)setDateOfBirth:(nullable NSDate*)dateOfBirth;
- (void)setGender:(FollowAnalyticsGender)gender;
- (void)setCountry:(nullable NSString*)country;
- (void)setCity:(nullable NSString*)city;
- (void)setRegion:(nullable NSString*)region;
- (void)setProfilePictureUrl:(nullable NSString*)profilePictureUrl;

func setFirstName(firstName : String?)
func setLastName(lastName: String?)
func setEmail(email : String?)
func setDateOfBirth(dateOfBirth : Date?)
func setGender(gender : FollowAnalyticsGender)
func setCountry(country : String?)
func setCity(region : String?)
func setRegion(city : String?)
func setProfilePictureUrl(profilePictureUrl : String?)

For instance, to set user Joe's city to "Paris", you would proceed as follows:

[FollowAnalytics.userAttributes setFirstName:@"Joe"];
[FollowAnalytics.userAttributes setCity:@"Paris"];

FollowAnalytics.userAttributes.setFirstName("Joe")
FollowAnalytics.userAttributes.setCity("Paris")

Custom attributes

In addition to predefined attributes, you can set your own custom attributes.

Set a custom attribute

To set custom attributes, you can call the following methods on the userAttributes property provided by the SDK:

- (void)setInteger:(NSInteger)integerValue forKey:(nonnull NSString*)key;
- (void)setDouble:(double)doubleValue forKey:(nonnull NSString*)key;
- (void)setString:(nonnull NSString*)string forKey:(nonnull NSString*)key;
- (void)setBoolean:(bool)boolean forKey:(nonnull NSString*)key;
- (void)setDate:(nonnull NSDate*)date forKey:(nonnull NSString*)key;
- (void)setDateTime:(nonnull NSDate*)dateTime forKey:(nonnull NSString*)key;
- (void)clear:(nonnull NSString*)key;
- (void)add:(nonnull NSSet<NSString*>*)values toSet:(nonnull NSString*)key;
- (void)remove:(nonnull NSSet<NSString*>*)values toSet:(nonnull NSString*)key;
- (void)clearSet:(nonnull NSString*)key;

func setInteger(integerValue: Int, forKey: String)
func setDouble(doubleValue : Double, forKey: String)
func setString(string: String, forKey: String)
func setBoolean(boolean: Bool, forKey: String)
func setDate(date: Date, forKey: String)
func setDateTime(dateTime: Date, forKey: String)
func clear(key: String)
func add(values: Set<String>, toSet: String)
func remove(values: Set<String>, toSet: String)
func clearSet(key: String)

For example, to set the user's job:

[FollowAnalytics.userAttributes setString:@"Taxi driver" forKey:@"job"];

FollowAnalytics.userAttributes.setString("Taxi driver", forKey:"job")

Delete a custom attribute value

You can delete the value of an attribute using its key. For instance, to delete the user's job:

[FollowAnalytics.userAttributes clear:@"job"];

FollowAnalytics.userAttributes.clear("job")

Set of Attributes

You can add or remove an item to or from a set of attributes.

To add an item to a set:

NSSet *set = [NSSet setWithObjects:@"apple", @"strawberry", @"lemon", nil];
[FollowAnalytics.userAttributes add:set toSet:@"fruits"]; // Adds "apple", "strawberry" and "lemon" to set "fruits".

FollowAnalytics.userAttributes.add(["apple", "strawberry", "lemon"], toSet:"fruits") // Adds "apple", "strawberry" and "lemon" to set "fruits".

To remove an item from a set:

NSSet *set = [NSSet setWithObjects:@"lemon", nil];
[FollowAnalytics.userAttributes remove:set toSet:@"fruits"]; // Removes "lemon" from set "fruits".

FollowAnalytics.userAttributes.remove(["lemon"], toSet:"fruits") // Removes "lemon" from set "fruits".

To clear a set:

[FollowAnalytics.userAttributes clearSet:@"fruits"]; // Removes all items from set "fruits".

FollowAnalytics.userAttributes.clearSet("fruits") // Removes all items from set "fruits".

Opt-in Analytics

FollowAnalytics SDK opt-in analytics state define whether to send logs and attributes to the platform. Opt-in analytics is true by default, meaning logs and attributes will be sent to FollowAnalytics platform.

You can set it to false at SDK initialization by setting the optInAnalyticsDefault parameter to false in the FollowAnalyticsConfiguration object passed to the initialization method. This is only used to set the default opt-in value at the first launch of the app.

This opt-in analytics value can be changed at runtime and it will be persisted for all future launch of the app.

To change opt-in analytics state at runtime, use the setOptInAnalytics method:

+ (void)setOptInAnalytics:(BOOL)state;

static func setOptIn(state: Bool)

This value is persisted in memory and the opt-in analytics state is changed for all subsequent launch of your application, meaning optInAnalyticsDefault is ignored.

To retrieve the current opt-in analytics state, use the getOptInAnalytics method:

+ (BOOL)getOptInAnalytics;

static func Bool getOptInAnalytics()

GDPR

You can record when the user expresses his demand to access or delete his personal data by calling one of the following methods:

[FollowAnalytics.GDPR requestToAccessMyData]
[FollowAnalytics.GDPR requestToDeleteMyData]

FollowAnalytics.gdpr.requestToAccessMyData()
FollowAnalytics.gdpr.requestToDeleteMyData()

The SDK will record all requests and send them to FollowAnalytics servers as soon as network conditions allow it. The SDK remembers pending requests between app restarts.

Campaigns

From the FollowAnalytics platform, you can create:

• Push campaigns, that will display messages as notifications, whether your app is opened or not;
• In-App campaigns, that will display messages inside your app, when it's opened.

The SDK take care of displaying campaigns, and provide you ways to customize and interact with messages received from the platform. In this section you will see how to:

• Add rich notifications and badge management capabilities to your app thanks to FANotificationExtension
• Handle link opening (website URLs, app links, and deep links) with the implementation of the shouldOpenURL callback
• Implement custom behavior on notification tap or reception thanks to the onNotificationTapped and onNotificationReceived callbacks
• Implement custom behavior on native In-App's buttons tap thanks to the onNativeInAppButtonTapped callback

Notification Service Extension Framework

Rich notifications are notifications with embedded rich media (images, GIFs, videos). When defining a Push campaign on the platform, you can add a rich media to the notification.

A badge is the number displayed on the icon of the app, indicating to the user that the app has new information. On the platform, you can set by how much the badge is to be increased or decreased at the notification reception on the user's device. This is defined as the badge increment in the Campaign Editor.

The SDK allows your app to receive rich notifications and to manage badges thanks to the FANotificationExtension notification service extension framework. In this section, we will see how to install and use this extension framework by:

• Adding a Notification Service Extension target
• Installing from CocoaPods or manually
• Setting an App Group for both app and extension targets
• Configuring the SDK to work with the extension
• Implementing the extension
• Managing badges

Add the Notification Service Extension target

To make your app able to receive rich notifications & badge incrementation, follow these steps:

1. In your XCode project, add a new target.
   
   

   
   
   

2. Select Notification Service Extension, give it a name, let's say Notification Service, and confirm. Then when prompted, activate the scheme.
   
   

   
   
   

3. Set the app as the Executable of the extension:

   • Choose the extension
   • Click Edit Scheme
     
     

   
   
   

   • Select app in executable field
     
     

   
   
   

Install FANotificationExtension from CocoaPods

If you want to use Cocoapods to manage your external dependencies, simply add the following line to your Podfile only in the extension target:

pod 'FANotificationExtension', '1.0.3', :source => 'https://github.com/followanalytics/fa-pod-spec.git'

If you don't have a podfile yet, open a console and do a pod init in your project directory.

Then, you only need to update your Cocoapods dependencies:

pod install

Install FANotificationExtension manually

If you want to manually integrate the .framework, extract the FollowAnalytics SDK archive and copy the FANotificationExtension.framework into your project directory.

1. Select the target of your main app, in Build Phases

   1. Press the + button, and select New Copy File Phase.
   2. Change the destination to Frameworks.
   3. Click in add other.
   4. Add the FANotificationExtension.framework file that you previously copied into your project directory.
   5. Uncheck Copy items if needed box.

2. Still in the Build Phases

   1. Press the + button, and select New Run Script Phase.

   2. Add this script:

      bash "PATH_TO_YOUR_PROJECT_DIRECTORY/FANotificationExtension.framework/strip-frameworks.sh"
      

      This step is required to work around an App Store submission bug when archiving universal binaries.

3. In Build Settings -> Framework Search Paths entry, add the path to where the FANotificationExtension.framework is located (actually your project directory).

Set an App Group for both app and extension targets

• Before all, an App Group must be created.

  • Go to the apple developer portal.
  • Choose the identifier tab.
  • Choose the App Groups filed from the list.
    
    

  

  • Tap + to create a new App Group
  • Create your App Group and click Continue
    
    

  

  • Switch to the App ID of the app.
  • Add App Groups capability
    
    

  

  • Select the new App Group recently created.
    
    

  

• Then, the app group must be added to the AppId of app and extension

• Finally, the app group capability must be activated in Xcode for both app and extension
  
  

Configuring the SDK to work with the extension

First, make sure you have set the proper App Group for the app target:

The appGroup parameter should be specified in the configuration init of the SDK:

FollowAnalyticsConfiguration* configuration = [FollowAnalyticsConfiguration
    configurationWith:^(FollowAnalyticsConfiguration* _Nonnull config) {
        ...
        config.appGroup = @"group.your.identifier";
    };
}];

let configuration = FollowAnalyticsConfiguration.init { (config) in
    ...
    config.appGroup = "group.your.identifier"
}

Implement the Notification Service Extension

First, make sure you have set the proper App Group for the extension target:

Copy and paste the following implementation in the NotificationService file of the extension you created

#import “NotificationService.h”
#import <FANotificationExtension/FANotificationExtension.h>

@interface NotificationService ()

@property(nonatomic, strong) void (^contentHandler)(UNNotificationContent* contentToDeliver);
@property(nonatomic, strong) UNMutableNotificationContent* bestAttemptContent;

@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest*)request
   withContentHandler:(void (^)(UNNotificationContent* _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];
    [FANotificationService
        getFAContentIfNeededWithRequest:request
                            bestContent:self.bestAttemptContent
                            appGroup:@"group.your.identifier"
                            completion:^(UNMutableNotificationContent* _Nullable newContent) {
                            NSLog(@"NotificationService: %@", request);
                            // Modify the notification content here...

                            self.contentHandler(newContent);
                            }];
}

- (void)serviceExtensionTimeWillExpire {
    // Called just before the extension will be terminated by the system.
    // Use this as an opportunity to deliver your "best attempt" at modified content,
    //otherwise the original push payload will be used.
    self.contentHandler(self.bestAttemptContent);
}
@end

import UserNotifications
import FANotificationExtension

class NotificationService: UNNotificationServiceExtension {

    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(_ request: UNNotificationRequest,
                                withContentHandler contentHandler:
                                @escaping (UNNotificationContent) -> Void) {
        self.contentHandler = contentHandler
        bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

        if let bestAttemptContent = bestAttemptContent,
        let contentHandler = self.contentHandler {
        // Modify the notification content here...

            FANotificationService.getFAContentIfNeeded(with: request,
                                                        bestContent: bestAttemptContent,
                                                        appGroup: "group.your.identifier") {
                                                        (newContent) in
                                                        if let newC = newContent {
                                                            contentHandler(newC)
                                                        }
            }
        }
    }

    override func serviceExtensionTimeWillExpire() {
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            contentHandler(bestAttemptContent)
        }
    }
}

Badge Management

Badges are the numbers displayed on the icon of the app, indicating to the user that the app has new information. Our service offers you two ways to update this value. The first one through the campaign editor on our platform and the second one using our SDK methods.

Using our platform, when creating a Push Campaign, it's possible to set a badge increment so that the SDK updates the badge number at push reception.

Using our SDK you can set, increment or get the badge number through the following methods respectively:

[FABadge setBadge:INTEGER]; // Set the value of the icon badge number
[FABadge updateBadgeBy:INTEGER]; // Update the value of the icon badge number
[FABadge badge]; // Get the value of the icon badge number

FABadge.setBadge(Int) // Set the value of the icon badge number
FABadge.updateBadgeBy(Int) // Update the value of the icon badge number
FABadge.badge // Get the value of the icon badge number

Geofencing triggers and location conditions

On the platform, when creating a campaign with contextual delivery, there are two ways to use locations:

• By defining a Geofencing Event trigger condition in the Contextual Delivery page of the campaign editor. The campaign will be displayed according to the type of geofence (entering or leaving area), the coordinates and the radius of the defined region. For Geofencing Events to work, it's required that your app requests the Always location authorization and that the user accepts it. Additionally, to allow the geofencing event to be triggered while your app is in background or force-quit, you must add the Location updates mode to the Background Modes capabilities of your project.

• By adding a Location Condition to a Session Events or Tagged Events trigger in the Contextual Delivery page of the campaign editor. To check the location condition, the SDK will use the last known location of your device, if this one is not older that 2H. If you want to increase the accuracy of this location condition, your app can explicitly request location updates through the CLLocationManager. Additionally, to allow location updates in the background, you must add the Location updates mode to the Background Modes capabilities of your project, and you must set allowsBackgroundLocationUpdates to true the CLLocationManager.

Implement custom behavior on URL opening

From the FollowAnalytics platform, you can add URLs (website links or custom URL schemes) to your Push or In-App campaigns. By default, those links will be opened by the SDK, unless the shouldOpenURL callback is defined on the FollowAnalyticsConfiguration provided at SDK initialization. This callback allows you to implement your own URL opening logic. Use the return value of this callback to allow the SDK to actually open the URL or not:

• If the return value is true the SDK will open the URL. In this case, if the URL is a Universal Link to your own website, it will not be opened into your app.

• If the return value is false the SDK will not open the URL. In this case, it's your responsibility to implement the opening of the URL. For instance, you can return false if you implemented code to open Universal Links in your app like in this example.

FollowAnalyticsConfiguration* configuration = [FollowAnalyticsConfiguration
    configurationWith:^(FollowAnalyticsConfiguration* _Nonnull config) {
        config.shouldOpenURL =
            ^BOOL(NSURL* _Nonnull url) {

            // YOUR BEHAVIOR

            // Returning `YES` tells the SDK to open the URL.
            return YES;
        }
    };
}];

let configuration = FollowAnalyticsConfiguration.init { (config) in
    config.shouldOpenURL = { (url) in

        // YOUR BEHAVIOR

        // Returning `true` tells the SDK to open the URL.
        return true
    }
}

Implement shouldOpenURL to handle Universal Links

Universal Links allow your app to be opened to handle links that point to your website. Due to the behavior of the open(_:options:completionHandler:) method, FollowAnalytics SDK will not open those links in your app, but in the browser. See this article from Apple documentation for more details.

In order to open those Universal Links in your app, you must implement the shouldOpenURL callback to forward the url to your application by calling the application(_:continue:restorationHandler:) callback:

config.shouldOpenURL = ^BOOL(NSURL* _Nonnull url) {

    BOOL urlHasBeenHandled = NO;

    // We only want to hanlde Universal Links
    // (i.e. http links that point to your own website).
    if ([url.absoluteString hasPrefix:@"http"]
        && [url.host isEqualToString:@"YOUR_WEBSITE_DOMAIN"]) {

        NSUserActivity* userActivity =
        [[NSUserActivity alloc] initWithActivityType:NSUserActivityTypeBrowsingWeb];

        userActivity.webpageURL = url;

        urlHasBeenHandled = [self application:UIApplication.sharedApplication
                            continueUserActivity:userActivity
                            restorationHandler:^(NSArray<id<UIUserActivityRestoring>> *
                                                _Nullable restorableObjects) { }];
    }

    // If the url has been handled by the application,
    // we don't want FA SDK to open the url.
    return !urlHasBeenHandled;
};

config.shouldOpenURL = { (url) in

    var urlHasBeenHandled = false

    // We only want to hanlde Universal Links
    // (i.e. http links that point to your own website).
    if url.absoluteString.hasPrefix("http")
        && url.host == "YOUR_WEBSITE_DOMAIN" {

        let userActivity = NSUserActivity(activityType:
            NSUserActivityTypeBrowsingWeb)

        userActivity.webpageURL = url

        urlHasBeenHandled = self.application(UIApplication.shared,
                                                continue: userActivity,
                                                restorationHandler: { _ in })
    }

    // If the url has been handled by the application,
    // we don't want FA SDK to open the url.
    return !urlHasBeenHandled
}

Make sure your implementation of application(_:continue:restorationHandler:) returns false when your app is not able to handle the provided url:

- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
restorationHandler:
(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {

    if (![userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
        return NO;
    }

    if (/* Check if userActivity.webpageURL should open screen 1 */) {

        // Present screen 1 ViewController

        return YES;
    }
    else if (/* Check if userActivity.webpageURL should open screen 2 */) {

        // Present screen 2 ViewController

        return YES;
    }

    return NO;
}

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([Any]?) -> Void) -> Bool {

    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb else { return false }

    if /* Check if userActivity.webpageURL should open screen 1 */ {

        // Present screen 1 ViewController

        return true
    }
    else /* Check if userActivity.webpageURL should open screen 2 */ {

        // Present screen 2 ViewController

        return true
    }

    return false
  }

Interactive Notifications

An Interactive Notification is a notification containing custom action buttons that the user can access by revealing the notification:

When tapped, an action button will:

• Close the notification.
• Eventually launch your application in the foreground, if you specified it explicitly when creating the action (See details below). Otherwise your app is not opened.
• Execute the custom behavior you implemented for the notification tap.

To create a campaign with Interactive Notifications:

• On the platform, create a Push Campaign and define a Category in the Interactive Notification section of the campaign editor. For our example, let's set this field to "NewContent".

  

• In your app, define the action names you want for your notification, we will call them actionIdentifiers. Those identifiers will be displayed as is on the platform in the Push Opened stats:

NSString* const ActionIdentifierView = @"View";
NSString* const ActionIdentifierDelete = @"Delete";
NSString* const ActionIdentifierRemind = @"Remind me tomorrow";

let ActionIdentifierView = "View"
let ActionIdentifierDelete = "Delete"
let ActionIdentifierRemind = "Remind me tomorrow"

• In the application(_:didFinishLaunchingWithOptions:) method of your app delegate, create the derised actions, add them to the "NewContent" category and register this category to the current UNUsernotificationCenter:

if (@available(iOS 10.0, *)) {

    UNNotificationAction *viewAction = [UNNotificationAction
                                        actionWithIdentifier:ActionIdentifierView
                                        title:NSLocalizedString(ActionIdentifierView, nil)
                                        options:UNNotificationActionOptionForeground];

    UNNotificationAction *deleteAction = [UNNotificationAction
                                           actionWithIdentifier:ActionIdentifierDelete
                                           title:NSLocalizedString(ActionIdentifierDelete, nil)
                                           options:UNNotificationActionOptionDestructive];

    UNNotificationAction *remindAction = [UNNotificationAction
                                         actionWithIdentifier:ActionIdentifierRemind
                                         title:NSLocalizedString(ActionIdentifierRemind, nil)
                                         options:UNNotificationActionOptionForeground];

    // The UNNotificationCategoryOptionCustomDismissAction option allows to
    // call the onNotificationTapped callback when the notiifcation is dismissed
    UNNotificationCategory *newContentCategory = [UNNotificationCategory
                                                 categoryWithIdentifier:@"NewContent"
                                                 actions:@[viewAction, deleteAction, remindAction]
                                                 intentIdentifiers:@[]
                                                 options:UNNotificationCategoryOptionCustomDismissAction];

    [[UNUserNotificationCenter currentNotificationCenter]
     setNotificationCategories:[NSSet setWithObject:newContentCategory]];
}

if #available(iOS 10.0, *) {

  let viewAction = UNNotificationAction(identifier: ActionIdentifierView,
                                        title: NSLocalizedString(ActionIdentifierView,
                                                                 comment: ""),
                                        options: .foreground)

  let deleteAction = UNNotificationAction(identifier: ActionIdentifierDelete,
                                          title: NSLocalizedString(ActionIdentifierDelete,
                                                                   comment: ""),
                                          options: .destructive)

  let remindAction = UNNotificationAction(identifier: ActionIdentifierRemind,
                                          title: NSLocalizedString(ActionIdentifierRemind,
                                                                   comment: ""),
                                          options: .foreground)

  // The customDismissAction option allows to call the onNotificationTapped
  // callback when the notiifcation is dismissed
  let newContentCategory =
    UNNotificationCategory(identifier: "NewContent",
                           actions: [viewAction, deleteAction, remindAction],
                           intentIdentifiers: [],
                           options: .customDismissAction)

  UNUserNotificationCenter.current().setNotificationCategories([newContentCategory])
}

Note that the notification action title is a localized version of the actionIdentifier, while the platform displays the actionIdentifier as is in the Push Opened stats.

Implement custom behavior on notification tap

You can implement a custom behavior when the user taps on a notification by implementing the onNotificationTapped callback in FollowAnalyticsConfiguration. This allows you to perform specific actions when a notification is tapped:

FollowAnalyticsConfiguration* configuration = [FollowAnalyticsConfiguration
    configurationWith:^(FollowAnalyticsConfiguration* _Nonnull config) {
        config.onNotificationTapped =
            ^(FANotificationInfo* _Nonnull notificationInfo, NSString* _Nonnull actionIdentifier) {

            if ([actionIdentifier isEqualToString:FANotificationDefaultActionIdentifier]) {
                // Your behavior for a tap on the notification body

            } else if ([actionIdentifier isEqualToString:FANotificationDismissActionIdentifier]) {

                // Your behavior when the notification is dismissed (only for Interactive Notification)

            } else if ([actionIdentifier isEqualToString:ActionIdentifierView]) {

                // Your behavior for a tap on the "View" action button

            } else if ([actionIdentifier isEqualToString:ActionIdentifierDelete]) {

                // Your behavior for a tap on the "Delete" action button

            } else if ([actionIdentifier isEqualToString:ActionIdentifierRemind]) {

                // Your behavior for a tap on the "Remind me tomorrow" action button

            }
        }
    };
}];

let configuration = FollowAnalyticsConfiguration.init { (config) in
    config.onNotificationTapped = { (notificationInfo, actionIdentifier) in

        switch (actionIdentifier) {

        case FANotificationDefaultActionIdentifier:
          // Your behavior for a tap on the notification body

        case FANotificationDismissActionIdentifier:
          // Your behavior when the notification is dismissed (only for Interactive Notification)

        case ActionIdentifierView:
          // Your behavior for a tap on the "View" action button

        case ActionIdentifierDelete:
          // Your behavior for a tap on the "Delete" action button

        case ActionIdentifierRemind:
          // Your behavior for a tap on the "Remind me later" action button

        default:
          // Do nothing
        }
    }
}

The SDK passes some Push campaign information to your app through this callback thanks to the notificationInfo argument, while the actionIdentifier argument provides information about which notification button has been tapped:

• notificationInfo.campaignId is a String containing the FollowAnalytics campaign identifier.
• notificationInfo.isSilent is a Boolean telling if the notification is silent or not. In onNotificationTapped, this property is always false.
• notificationInfo.parameters is an optional Dictionary containing the key/value pairs defined in the campaign editor.
• notificationInfo.url is an optional URL containing App Link value defined in the campaign editor.
• actionIdentifier is a String containing the identifier for the tap action. It can be either :
  • FANotificationDefaultActionIdentifier when the user tapped on a regular notification, or on the body of an Interactive Notification.
  • FANotificationDismissActionIdentifier when the user dismissed an Interactive Notification.
  • Your custom action identifier when the user tapped on a custom button of an Interactive Notification.

Implement custom behavior on Push reception

You can implement a custom behavior when the device receives a message from a Push campaign that contains custom parameters (i.e. at least one key/value pair). This can be used to fetch data from your server if a particular custom parameter is defined in the Push message. To do so, implement the onNotificationReceived callback in FollowAnalyticsConfiguration:

FollowAnalyticsConfiguration* configuration = [FollowAnalyticsConfiguration
    configurationWith:^(FollowAnalyticsConfiguration* _Nonnull config) {
        config.onNotificationReceived = ^(FANotificationInfo * _Nonnull notificationInfo){
            // YOUR BEHAVIOR
        }
    };
}];

let configuration = FollowAnalyticsConfiguration.init { (config) in
    config.onNotificationReceived = { (notificationInfo) in
        // YOUR BEHAVIOR
    }
}

The SDK passes some Push campaign information to your app through this callback thanks to the notificationInfo argument:

• notificationInfo.campaignId is a String containing the FollowAnalytics campaign identifier.
• notificationInfo.isSilent is a Boolean telling if the notification is silent or not.
• notificationInfo.parameters is an optional Dictionary containing the key/value pairs defined in the campaign editor. In onNotificationReceived, this property is always set with at least one key/value pair.
• notificationInfo.url is an optional URL containing App Link value defined in the campaign editor.

Implement custom behavior on Native Alert button tap

You can implement a custom behavior when the user taps on a Native Alert* button by implementing the onNativeInAppButtonTapped callback in the FollowAnalyticsConfiguration. This allows you to perform specific actions when a native alert button is tapped:

FollowAnalyticsConfiguration* configuration = [FollowAnalyticsConfiguration
    configurationWith:^(FollowAnalyticsConfiguration* _Nonnull config) {
        config.onNativeInAppButtonTapped =
            ^(FACustomButtonInfo* _Nonnull buttonInfo) {
            // YOUR BEHAVIOR
        }
    };
}];

let configuration = FollowAnalyticsConfiguration.init { (config) in
    config.onNativeInAppButtonTapped = { (buttonInfo) in
        // YOUR BEHAVIOR
    }
}

The SDK passes some Native Alert campaign information to your app through this callback thanks to the buttonInfo argument:

• buttonInfo.campaignId is a String containing the FollowAnalytics campaign identifier.
• buttonInfo.parameters is an optional Dictionary containing the key/value pairs defined in the campaign editor.
• buttonInfo.url is an optional URL containing App Link value defined in the campaign editor.

Controlling In-App campaigns

To pause and resume campaigns, add the following methods in you code at the location you wish the pause and resume to take effect:

[FollowAnalytics.inApp pauseCampaignDisplay]
[FollowAnalytics.inApp resumeCampaignDisplay]

FollowAnalytics.inApp.pauseCampaignDisplay()
FollowAnalytics.inApp.resumeCampaignDisplay()

Archiving messages

FollowAnalytics SDK allows you to store campaigns's messages received by your app. This makes them available for custom usage, like building an inbox feature. All campaigns displayed by a device can be archived locally and accessed from the developer's code, formatted as a FAMessage object. In order to configure your campaign storage, you have to set the following FollowAnalyticsConfiguration properties at SDK initialization:

@property(nonatomic, readonly, assign) BOOL archivePushMessages;
@property(nonatomic, readonly, assign) BOOL archiveInAppMessages;

open var archivePushMessages: Bool { get }
open var archiveInAppMessages: Bool { get }

In FollowAnalyticsInApp and FollowAnalyticsPush protocols you will find all necessary methods to manage all FAMessage objects that are archived. They are implemented by FollowAnalytics.inApp and FollowAnalytics.push

• The methods are the following

- (nonnull NSArray<FAMessage*>*)getAll;
- (nullable FAMessage*)get:(nonnull NSString*)identifier;
- (void)markAsRead:(nonnull NSArray<NSString*>*)identifiers;
- (void)markAsUnread:(nonnull NSArray<NSString*>*)identifiers;
- (void)deleteIdentifiers:(nonnull NSArray<NSString*>*)identifiers;

func getAll() -> [FAMessage]
func get(identifier : String) -> FAMessage
func markAsRead(identifiers : [String])
func markAsUnread(identifiers : [String])
func deleteIdentifiers(identifiers : [String])

Here is a description of some of the FAMessage attributes:

Data Wallet

If you want to use Data Wallet, the very first step is to enable it in your app at startup. This is done by setting isDataWalletEnabled property to true in the FollowAnalyticsConfiguration object passed to the SDK initialization method.

Policy download and consent

Now that the Data Wallet is enabled, the SDK will automatically download the new policies as they are published. In order to deal with the currently known policy, call the following APIs:

// gets the current policy
id<FADataWalletPolicy> policy = [FollowAnalytics.dataWallet getPolicy];

// true if the current policy is considered accepted
BOOL policyIsRead =  FollowAnalytics.dataWallet.isRead;

// informs the SDK that the user has accepted the current policy
[FollowAnalytics.dataWallet setIsRead:true];

// gets the current policy
var policy = FollowAnalytics.dataWallet.getPolicy()

// true if the current policy is considered accepted
var policyIsRead =  FollowAnalytics.dataWallet.isRead()

// informs the SDK that the user has accepted the current policy
FollowAnalytics.dataWallet.setIsRead(true)```

There could only be one active policy at a time. When a new policy becomes available online, the SDK will call on the main thread onDataWalletPolicyChange, callback set on the FollowAnalyticsConfiguration. To set this up before starting the SDK, include the following code:

FollowAnalyticsConfiguration* configuration = [FollowAnalyticsConfiguration
    configurationWith:^(FollowAnalyticsConfiguration * _Nonnull config) {
      config.isDataWalletEnabled = true;
      config.onDataWalletPolicyChange = ^{
        [self displayNewPolicy];
    };
}];

let configuration = FollowAnalyticsConfiguration.init { (config) in
  config.isDataWalletEnabled = true;
  config.onDataWalletPolicyChange = {
    //YOUR_BEHAVIOR;
  }
}

At each major policy update, there needs to be consent from the client. When the user accepts a policy call [FollowAnalytics.dataWallet setIsRead:true] to mark the current policy as "read". In other words:

• If FollowAnalytics.dataWallet.isRead is false, the current policy major version has yet to be accepted by the user.
• If the current policy is accepted, FollowAnalytics.dataWallet.isRead becomes true.

The SDK records the major version of the current policy for future reference. By default, if no other configuration is present, the SDK will return a default policy with version 0.0. This policy is always read. You should check for version 0.0 and handle it appropriately.

Custom default policy

If you want to provide a custom default policy for your users, download the policy JSON file from the back office and add it to your app, then modify the configuration to use it as follows:

FollowAnalyticsConfiguration* configuration = [FollowAnalyticsConfiguration
  configurationWith:^(FollowAnalyticsConfiguration * _Nonnull config) {
    // assuming that you have Policy.json in you main bundle
    config.dataWalletDefaultPolicyPath = [[NSBundle mainBundle] pathForResource:@"Policy"
                                                                ofType:@"json"];
}];

let configuration = FollowAnalyticsConfiguration.init { (config) in
     config.dataWalletDefaultPolicyPath = Bundle.main.path(forResource: "Policy",
                                                              ofType: "JSON")
  }

Web Views

If your app contains web views, you can use FollowAnalytics SDK from within your HTML/JS code. This is possible thanks to the FAWKWebViewJSBridge, which you can use by following those steps:

1. Adopt the WKUIDelegate protocol in your object of choice, typically a UIViewController.

   Objective-C

   @interface ViewController <WKUIDelegate>
   

   Swift

   class ViewController: UIViewController, WKUIDelegate {
   

2. At the initialization of the hosting view controller, keep a strong reference to a FAWKWebViewJSBridge instance:

   Objective-C

   @property(nonatomic, nullable) FAWKWebViewJSBridge* webViewJSBridge;
   // ...
   self.webViewJSBridge = [[FAWKWebViewJSBridge alloc] init];
   

   Swift

   var webViewJSBridge: FAWKWebViewJSBridge?
   // ...
   self.webViewJSBridge = FAWKWebViewJSBridge()
   

3. Add the FAWKWebViewJSBridge instance to the WKWebViewConfiguration instance, pass this configuration to the WKWebView and set your UIViewController as the web view delegate:

   Objective-C

   WKWebViewConfiguration *configuration = [[WKWebViewConfiguration alloc] init];
   [self.webViewJSBridge addToConfiguration:configuration];
   WKWebView* webView = [[WKWebView alloc] initWithFrame:self.view.frame configuration:configuration];
   webView.UIDelegate = self;
   

   Swift

   let configuration = WKWebViewConfiguration()
   self.webViewJSBridge?.add(to: configuration)
   let webView = WKWebView.init(frame: self.view.frame, configuration: configuration)
   webView.uiDelegate = self
   

4. Implement the following delegate method:

   Objective-C

   - (void)webView:(WKWebView *)webView
                 runJavaScriptTextInputPanelWithPrompt:(NSString *)prompt
                 defaultText:(nullable NSString *)defaultText
                 initiatedByFrame:(WKFrameInfo *)frame
                 completionHandler:(void (^)(NSString * _Nullable result))completionHandler {
     if([prompt hasPrefix:@"FollowAnalytics"]) {
       [self.webViewJSBridge webView:webView
             runJavaScriptTextInputPanelWithPrompt:prompt
             defaultText:defaultText
             initiatedByFrame:frame
             completionHandler:completionHandler];
         return;
     }
   }
   

   Swift

   func webView(_ webView: WKWebView,
                runJavaScriptTextInputPanelWithPrompt prompt: String,
                defaultText: String?,
                initiatedByFrame frame: WKFrameInfo,
                completionHandler: @escaping (String?) -> Void) {
     if prompt.hasPrefix("FollowAnalytics") {
       self.webView(webView,
                    runJavaScriptTextInputPanelWithPrompt: prompt,
                    defaultText: defaultText,
                    initiatedByFrame: frame,
                    completionHandler: completionHandler
       return
     }
   }
   

Tagging events/errors/locations can be performed in the HTML file by using the following methods:

FollowAnalytics.logError('err1', 'str value')
FollowAnalytics.logEvent('event1', 'str value')
FollowAnalytics.logLocation(-21.544805, 165.6629343)

The complete list of JavaScript methods is documented in FAWKWebViewJSBridge.h .

Disabling Swizzling

By default, the SDK swizzles your UIApplicationDelegate methods and your UNUserNotificationCenterDelegate methods. This is an automatic process that allows the SDK to receive the necessary system calls seamlessly and behave accordingly without additional configurations and calls from the developer.

But in some situations, you could have the need to disable this feature. For example due to a legacy framework for some incompatibility with the swizzled methods.

In these cases we allow the developer to disable the Swizzling. To that, include the swizzlingEnabled options in the configuration as follows:

FollowAnalyticsConfiguration* configuration = [FollowAnalyticsConfiguration
  configurationWith:^(FollowAnalyticsConfiguration * _Nonnull config) {
    config.swizzlingEnabled = NO;
}];

let configuration = FollowAnalyticsConfiguration.init { (config) in
     config.swizzlingEnabled = false
  }

Required Methods

The required UIApplicationDelegate methods are:

1. didRegisterForRemoteNotificationsWithDeviceToken:

   Forwarding this method the SDK will be able to send the device token to the server for Push Notifications delivery.

   Objective-C

   - (void) application:(UIApplication*) application didRegisterForRemoteNotificationsWithDeviceToken:(NSData*) deviceToken {
     [FollowAnalytics didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
   }
   

   Swift

   func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
     FollowAnalytics.application(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
   }
   

2. applicationDidEnterBackground:

   Forwarding this method the SDK will be able to calculate session duration, handle app badge number and detect campaign triggers.

   Objective-C

   - (void) applicationDidEnterBackground:(UIApplication*_Nonnull) application {
     [FollowAnalytics applicationDidEnterBackground:application];
   }
   

   Swift

   func applicationDidEnterBackground(_ application: UIApplication) {
     FollowAnalytics.applicationDidEnterBackground(application)
   }
   

3. applicationWillEnterForeground:

   Forwarding this method the SDK will be able to synchronize campaigns, detect campaign triggers and present queued triggered campaigns.

   Objective-C

   - (void) applicationWillEnterForeground:(UIApplication*_Nonnull) application {
     [FollowAnalytics applicationWillEnterForeground:application];
   }
   

   Swift

   func applicationWillEnterForeground(_ application: UIApplication) {
     FollowAnalytics.applicationWillEnterForeground(application)
   }
   

4. applicationDidBecomeActive:

   Forwarding this method the SDK will be able to calculate sessions durations and detect campaign triggers.

   Objective-C

   - (void) applicationDidBecomeActive:(UIApplication*_Nonnull) application {
     [FollowAnalytics applicationDidBecomeActive:application];
   }
   

   Swift

   func applicationDidBecomeActive(_ application: UIApplication) {
     FollowAnalytics.applicationDidBecomeActive(application)
   }
   

5. applicationWillTerminate:

   Forwarding this method the SDK will be able to calculate sessions durations and handle app badge number.

   Objective-C

   - (void) applicationWillTerminate:(UIApplication*_Nonnull) application {
     [FollowAnalytics applicationWillTerminate:application];
   }
   

   Swift

   func applicationWillTerminate(_ application: UIApplication) {
     FollowAnalytics.applicationWillTerminate(application)
   }
   

6. applicationDidReceiveMemoryWarning:

   Forwarding this method the SDK will be able to send statistics information.

   Objective-C

   - (void) applicationDidReceiveMemoryWarning:(UIApplication*_Nonnull) application {
     [FollowAnalytics applicationDidReceiveMemoryWarning:application];
   }
   

   Swift

   func applicationDidReceiveMemoryWarning(_ application: UIApplication) {
     FollowAnalytics.applicationDidReceiveMemoryWarning(application)
   }
   

7. didReceiveRemoteNotification:

   Forwarding this method the SDK will be able to handle Push Notifications and In-App campaigns.

   Objective-C

   - (void) application:(UIApplication*_Nonnull) application didReceiveRemoteNotification:(NSDictionary*_Nullable) userInfo {
     [FollowAnalytics application:application didReceiveRemoteNotification:userInfo];
   }
   

   Swift

   func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any]) {
     FollowAnalytics.application(application, didReceiveRemoteNotification: userInfo)
   }
   

8. handleActionWithIdentifierForRemoteNotification:

   Forwarding this method the SDK will be able to handle Push Notifications and In-App campaigns.

   Objective-C

   - (void) application:(UIApplication*_Nonnull) application handleActionWithIdentifier:(NSString*_Nullable) identifier forRemoteNotification:(NSDictionary*_Nonnull) userInfo completionHandler:(void (^_Nullable)(void)) completionHandler {
     [FollowAnalytics application:application handleActionWithIdentifier:identifier forRemoteNotification:userInfo completionHandler:completionHandler];
   }
   

   Swift

   func application(_ application: UIApplication, handleActionWithIdentifier identifier: String?, forRemoteNotification userInfo: [AnyHashable: Any], completionHandler: @escaping () -> Void) {
     FollowAnalytics.application(application, handleActionWithIdentifier: identifier, forRemoteNotification: userInfo, completionHandler: completionHandler)
   }
   

9. handleActionWithIdentifierForLocalNotification:

   Forwarding this method the SDK will be able to handle Notifications and In-App campaigns.

   Objective-C

   - (void) application:(UIApplication*_Nonnull) application handleActionWithIdentifier:(NSString*_Nullable) identifier forLocalNotification:(UILocalNotification*_Nonnull) notification completionHandler:(void (^_Nullable)(void)) completionHandler {
     [FollowAnalytics application:application handleActionWithIdentifier:identifier forLocalNotification:notification completionHandler:completionHandler];
   }
   

   Swift

   func application(_ application: UIApplication, handleActionWithIdentifier identifier: String?, for notification: UILocalNotification, completionHandler: @escaping () -> Void) {
     FollowAnalytics.application(application, handleActionWithIdentifier: identifier, for: notification, completionHandler: completionHandler)
   }
   

10. handleOpenURL:

    If your application support iOS version less than 9.0.

    Forwarding this method the SDK will be able to present alerts about the current user status if the URL is related to this SDK.

    Objective-C

    - (BOOL) application:(UIApplication*_Nonnull) application handleOpenURL:(NSURL*_Nonnull) url {
      return [FollowAnalytics application:application handleOpenURL:url];
    }
    

    Swift

    func application(_ application: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any] = [:]) -> Bool {
      return FollowAnalytics.application(application, open: url, options: options)
    }
    

11. openURLSourceApplication:

    If your application support iOS version less than 9.0.

    Forwarding this method the SDK will be able to present alerts about the current user status if the URL is related to this SDK.

    Objective-C

    - (BOOL) application:(UIApplication*_Nonnull) application openURL:(NSURL*_Nonnull) url sourceApplication:(NSString*_Nullable) sourceApplication annotation:(id _Nonnull) annotation {
      return [FollowAnalytics application:application openURL:url sourceApplication:sourceApplication annotation:annotation];
    }
    

    Swift

    func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
      return FollowAnalytics.application(application, open: url, sourceApplication: sourceApplication, annotation: annotation)
    }
    

12. openURLOptions:

    Forwarding this method the SDK will be able to present alerts about the current user status if the URL is related to this SDK.

    Objective-C

    - (BOOL) application:(UIApplication*_Nonnull) application handleOpenURL:(NSURL*_Nonnull) url {
      return [FollowAnalytics application:application handleOpenURL:url];
    }
    

    Swift

    func application(_ application: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any] = [:]) -> Bool {
      return FollowAnalytics.application(application, open: url, options: options)
    }
    

13. didReceiveLocalNotification:

    Forwarding this method the SDK will be able to handle In-App campaigns.

    Objective-C

    - (void) application:(UIApplication*_Nonnull) application didReceiveLocalNotification:(UILocalNotification*_Nonnull) notification {
      [FollowAnalytics application:application didReceiveLocalNotification:notification];
    }
    

    Swift

    func application(_ application: UIApplication, didReceive notification: UILocalNotification) {
      FollowAnalytics.application(application, didReceive: notification)
    }
    

14. performFetchWithCompletionHandler:

    Forwarding this method the SDK will be able to close sessions and fetch contents.

    Objective-C

    - (void) application:(UIApplication*_Nonnull) application performFetchWithCompletionHandler:(void (^_Nullable)(UIBackgroundFetchResult)) completionHandler {
      [FollowAnalytics application:application performFetchWithCompletionHandler:completionHandler];
    }
    

    Swift

    func application(_ application: UIApplication, performFetchWithCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
      FollowAnalytics.application(application, performFetchWithCompletionHandler: completionHandler)
    }
    

15. didReceiveRemoteNotificationFetchCompletionHandler:

    Forwarding this method the SDK will be able to synchronize campaigns, handle the badge icon and detect campaign triggers.

    Objective-C

    - (void) application:(UIApplication*_Nonnull) application didReceiveRemoteNotification:(NSDictionary*_Nonnull) userInfo fetchCompletionHandler:(void (^_Nonnull)(UIBackgroundFetchResult)) completionHandler {
      [FollowAnalytics application:application didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
    }
    

    Swift

    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
      FollowAnalytics.application(application, didReceiveRemoteNotification: userInfo, fetchCompletionHandler: completionHandler)
    }
    

16. handleEventsForBackgroundURLSession:

    Forwarding this method the SDK will be able to synchronize campaigns, handle the badge icon and detect campaign triggers.

    Objective-C

    - (void) application:(UIApplication*_Nonnull) application handleEventsForBackgroundURLSession:(NSString*_Nonnull) identifier completionHandler:(void (^_Nullable)(void)) completionHandler {
      [FollowAnalytics application:application handleEventsForBackgroundURLSession:identifier completionHandler:completionHandler];
    }
    

    Swift

    func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {
      FollowAnalytics.application(application, handleEventsForBackgroundURLSession: identifier, completionHandler: completionHandler)
    }
    

The required UNUserNotificationCenterDelegate methods are:

1. didReceiveNotificationResponse:

   Forwarding this method the SDK will be able to handle Push Notifications and In-App campaigns.

   Objective-C

   - (void) userNotificationCenter:(UNUserNotificationCenter*) center didReceiveNotificationResponse:(UNNotificationResponse*) response withCompletionHandler:(void (^)(void)) completionHandler {
     [FollowAnalytics userNotificationCenter:center didReceiveNotificationResponse:response withCompletionHandler:completionHandler];
   }
   

   Swift

   func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
     FollowAnalytics.userNotificationCenter(center, didReceive: response, withCompletionHandler: completionHandler)
   }
   

2. willPresentNotification:

   Forwarding this method the SDK will be able to handle Push Notifications and In-App campaigns.

   Objective-C

   - (void) userNotificationCenter:(UNUserNotificationCenter*) center willPresentNotification:(UNNotification*) notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions)) completionHandler {
     [FollowAnalytics userNotificationCenter:center willPresentNotification:notification withCompletionHandler:completionHandler];
   }
   

   Swift

   func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
     FollowAnalytics.userNotificationCenter(center, willPresent: notification, withCompletionHandler: completionHandler)
   }
   

Configuration

To customize the SDK behavior, you must define your desired SDK parameters by setting the related properties values on the FollowAnalyticsConfiguration object passed to the SDK initialization method:

Updating from older versions

Updating from 6.4 to 6.5

• Now, by default, the last known location is no longer logged when a session starts. If you want to enable this feature you must set the configuration parameter lastKnownLocationEnabled to true from the FollowAnalyticsConfiguration object passed to the SDK initialization.

Updating from 6.4.0 to 6.4.1

• The automaticallyOpenNotificationURL Configuration parameter is now replaced by the shouldOpenURL callback. If you had automaticallyOpenNotificationURL set to false, or if you want to handle Universal Links to your own website, consider implementing shouldOpenURL. It allows you to define the behavior when an URL is about to be opened by the SDK. More information in the Implement custom behavior on URL opening section.
• Calling FABage.enable() is no longer necessary because now badges are always enabled. More information in the badge management section.

Updating from 6.3 to 6.4

• Consider calling requestProvisionalNotificationAuthorization() at app launch, to allow your app to receive quiet notifications from FollowAnalytics platform.
• Replace your call to requestNotificationCenterDefaultAuthorisation() by requestNotificationAuthorization(), and consider calling this method in the right place in your user journey.
• Update your implementation of onNotificationTapped according to its new signature. Now it take a non-null notificationInfo object and a non-null actionIdentifier string. The url and params you usually got in the previous signature are now accessible through the notificationInfo object. More information in the onNotificationTapped section.
• From 6.4.0, by default, your implementation of onNotificationTapped no longer needs to open the received url, indeed the url is automatically opened by the SDK when automaticallyOpenURL is set to true in the SDK configuration. See Handling links section for more details.
• Update your implementation of onNotificationReceived according to its new signature. Now it takes a non-null notificationInfo object. Make sure to make your implementation following the required rules defined in the onNotificationReceived section.
• Implement onNativeInAppButtonTapped to handle the tap on Native Alert custom buttons. More information in the onNativeInAppButtonTapped section.
• Note that onOpenURL, onIncomingCustomCampaign and onIncomingDeepLink callbacks are no longer available. Make sure to migrate your code logic to adopt the new callbacks.
• Now calling enableGeofencing() in no longer needed, geofencing works out of the box as soon as your app get the "Always" location authorization.
• Prior to 6.4.0, for apps that had the location authorization and that was calling enableGeofencing(), the SDK was requesting periodic location updates internally and was sending locations logs to the FollowAnalytics platform. Since 6.4.0, it's the responsibility of the developer to send location logs to the platform by using the new logLocation() methods, as explained in the Logging Locations section.

Updating from 6.2 to 6.3

If your app implements onIncomingDeepLink and onOpenURL callbacks:

• Move your current implementation of onIncomingDeepLink to onNotificationReceived and make necessary changes
• Add onNotificationTapped and onNotificationReceived callbacks
• Move your current implementation of onOpenURL to onNotificationTapped and make necessary changes. You you want to open the url passed as argument to this callback, you will have to add your own code to do so.

Updating from 6.1 to 6.2

• Replace debug by isVerbose in FollowAnalyticsConfiguration

Updating to 6.0

• Replace all undefined methods with corresponding methods defined by the new FollowAnalytics interfaces
• For manual integration, do not forward anymore delegate methods to FollowAnalytics. We automatically intercept the invocations when needed.
• Remove UserNotifications.framework and MobileCoreServices.framework from all your targets.

Updating from 5.3 to 5.4

• Change imports from <FollowApps/...> to <FollowAnalytics/...>
• Previous versions of opt-out via settings bundle are deprecated and completely removed starting with version 6 of the SDK. While still available, a warning shall be sent to log about the deprecated use. The new 5.4 opt-out feature must be used for RGPD compliance.
• if using change strip framework to the new ${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/FollowAnalytics.framework/strip-frameworks.sh

Updating from 5.2 to 5.3

• In your Podfile replace pod FollowApps by pod FollowAnalytics

Updating from 5.0 to 5.1

• Replace this method:

  + (BOOL)configureWithId:(nonnull NSString *)FAId
             debugStateOn:(BOOL)isDebug
                  options:(nonnull NSDictionary *)options;
  

  by

  + (BOOL)configureWithId:(nonnull NSString *)FAId
           sharedAppGroup:(nullable NSString * )appGroup
               automatise:(BOOL)automatise
             debugStateOn:(BOOL)isDebug
                  options:(nullable NSDictionary *)options;
  

• If you used the badge management, you have to specify your appGroup shared between the app and the notification service extension.

• If you use geofencing in your app. You have to call this method : + (void)enableGeofencing;

Updating from 4 to 5.0.0

To use version 5.0.0+ of the iOS SDK:

• Link these additional Frameworks in the Settings of your targets:
  • UserNotifications.framework.
  • MobileCoreServices.framework.
  • libz.tbd.
• PassKit is not required anymore. If you don't use it you can remove it.

• Replace these deprecated methods:

  + (void)addCustomUserAttributeSet:(NSSet *)attributeSet forKey:(NSString *)key
  + (BOOL)removeCustomUserAttribute:(NSString *)attribute fromSetWithKey:(NSString *)key //Remove one element from the specify set.
  

  by:

  + (BOOL)addCustomUserAttribute:(NSString *)attribute toSetWithKey:(NSString *)key //Add only one string element into the specify set
  + (BOOL)removeCustomUserAttributeSet:(NSSet *)set fromSetWithKey:(NSString *)key // remove a set of string element from a specify set
  

Updating from 3.* to 4.*

The migration is seamless. However, please refer to the section around user attributes to learn how to feed user profiles using the SDK.

Updating from 2.* to 3.0.0

To use version 3.0.0+ of the iOS SDK:

• Link an additional Framework in the Settings of your targets: libsqlite3.dylib.

• In your AppDelegate.m file, replace this deprecated method:

  - (void)followAppsShouldHandleParameters:(NSDictionary *)openingParameters
  

  with:

  - (void)followAppsShouldHandleParameters:(NSDictionary *)customParameters
                          actionIdentifier:(NSString *)actionIdentifier
                               actionTitle:(NSString *)actionTitle
                         completionHandler:(void (^)())completionHandler
  

These new parameters are provided only when running on iOS 8 and later. They are the interactive notification parameters that you would want to get to know which action was performed on a FollowAnalytics notification.

Nothing else changes. Please refer to the rest of the documentation to discover what the newer versions of the SDK now allow.