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 from CocoaPods
• Installing the SDK in your project with Switft Package Manager
• Initializing the SDK using your API key
• Setting up push 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.9.0' 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.

Installation from Swift Package Manager

| Package Link: https://github.com/followanalytics/FollowAnalytics-SDK-iOS-SPM

1. Head over to your project in Xcode and Click File -> Swift Packages -> Add Package Dependency.

   

2. From the wizard enter the package link and proceed.

   

3. Select the pretended version or select master to keep up with the latest versions and complete.

   

4. Select your project target to the FollowAnalytics framework and select your Notification Extension to the FANotificationExtension framework.

   

5. After complete the dependencies should exist on the left menu of your project.

   

Manual installation

Setting up FollowAnalytics SDK on Xcode 12.3 and greater

1. Copy the FollowAnalytics.framework into your project directory. If you want to use it from a different directory you also need to update the Framework Search Paths from the Build Settings with that directory.

2. Go to your Xcode project’s General settings of your target, drag and drop the FollowAnalytics.framework in the Frameworks, Libraries, and Embedded Content section. Make sure Do Not Embed is set for the FollowAnalytics.framework.

   

3. From the Build Settings tap on the + button and select Add User-Defined Setting. Name the setting as FA_SDK_PATH and indicate the finder path where the FollowAnalytics.framework exist. E.g. if you have the framework inside a folder named Frameworks on the project root use $SRCROOT/Frameworks.

   

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

   bash "${FA_SDK_PATH}/FollowAnalytics.framework/embed-frameworks.sh"
   

   This step is required to work around an App Store submission bug when archiving universal binaries and to work around the linker about multi architecrture configurations.

Setting up FollowAnalytics SDK on Xcode 12.2 and below

1. Copy the FollowAnalytics.framework into your project directory. If you want to use it from a different directory you also need to update the Framework Search Paths from the Build Settings with that directory.

2. Go to your Xcode project’s General settings of your target, drag and drop the FollowAnalytics.framework in the Frameworks, Libraries, and Embedded Content section.

   

3. 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";
      #if DEBUG
      config.apiMode = FollowAnalyticsAPIModeDev;
      #else
      config.apiMode = FollowAnalyticsAPIModeProd;
      #endif
    }];
  [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"
      #if DEBUG
      config.apiMode = .dev
      #else
      config.apiMode = .prod
      #endif
    }
    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.

On Xcode 12.3 and greater

1. Go to your Xcode project’s General settings of your extension target, drag and drop the FANotificationExtension.framework in the Frameworks, Libraries, and Embedded Content section. Make sure Do Not Embed is set for the FANotificationExtension.framework.

2. From the Build Settings tap on the + button and select Add User-Defined Setting. Name the setting as FA_SDK_PATH and indicate the finder path where the FANotificationExtension.framework exist. E.g. if you have the framework inside a folder named Frameworks on the project root use $SRCROOT/Frameworks.

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

   bash "${FA_SDK_PATH}/FANotificationExtension.framework/embed-frameworks.sh"
   

   This step is required to work around an App Store submission bug when archiving universal binaries and to work around the linker about multi architecrture configurations.

On Xcode 12.2 and below

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 create a new Run Script Phase in your app’s extension target Build Phases and paste the following snippet in the script text field:

   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
  }

Opt-in Notifications

The FollowAnalytics SDK opt-in notifications status defines whether your app will receive notifications from your Push campaigns. Opt-in notifications is true by default, meaning notifications from your Push campaigns will be received by your app. This status is independent from the iOS notification authorization, which is also needed by your app to display notifications.

Thanks to this opt-in notifications status, you can implement a UI in your app to allow to choose whether to receive notifications, without the need to go to the iOS notification authorization settings. Note that the opt-in notifications status will have no effect if the iOS notification authorization is not allowed, and in this case, your app will not receive notifications from your Push campaigns, whatever the opt-in notifications status. To have the iOS notification authorisation allowed, use the requestNotificationAuthorization method or the requestProvisinalNotificationAuthorization method.

To update your app UI to reflect the current opt-in notifications status, use the getOptInNotifications method:

+ (BOOL)getOptInNotifications;

static func Bool getOptInNotifications()

To update the current opt-in notifications status upon UI change, use the setOptInNotifications method:

+ (void)setOptInNotifications:(BOOL)state;

static func setOptInNotifications(state: Bool)

It's possible to set the opt-in notifications status to false at the SDK initialization by setting the optInNotificationsDefault 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. Note that calling the setOptInNotifications will persist the opt-in notifications status for all subsequent launch of your application, meaning optInNotificationsDefault will be ignored.

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 notification sound

When creating a Push Campaign, the editor lets you set a custom sound for the notification:

To configure a custom sound:

• Add a custom sound file to your app's main bundle or make your app store it in the Library/Sounds folder of your app's container directory. See more details about file location and format in Apple documentation.
• Enter the complete custom sound filename in the "Custom Sound" field of the campaign editor.

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.messageId is a String containing the FollowAnalytics message identifier. It can be used to retrieve the associated FAMessage by calling FollowAnalytics.push.get(notificationInfo.messageId).
• 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.messageId is a String containing the FollowAnalytics message identifier. It can be used to retrieve the associated FAMessage by calling FollowAnalytics.push.get(notificationInfo.messageId).
• 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:

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.

Using FAWKWebViewJSBridge

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
     }
   }
   

FollowAnalytics SDK JS interface

Here are the SDK methods you can call from the JavaScript code:

• Environment information and actions:

  FollowAnalytics.getUserId();
  FollowAnalytics.setUserId("aUserId");
  FollowAnalytics.getSDKPlatform();
  FollowAnalytics.getSDKVersion();
  FollowAnalytics.getDeviceId();
  FollowAnalytics.setOptInNotifications(false);
  FollowAnalytics.getOptInNotifications(); // Returns the string "true" if the opt-in notifications status is true, "false" otherwhise.
  FollowAnalytics.requestNotificationAuthorization(); // To request Notification authorization permissions.
  FollowAnalytics.requestProvisionalNotificationAuthorization(); // To request provisional Notification authorization.
  FollowAnalytics.isRegisteredForPushNotifications() // Get the Push campaigns registration status. Will return "true" only if the notification authorization is allowed AND the SDK opt-in notifications status is true. Otherwise, will return "false".
  FollowAnalytics.openNotificationSettingsEventually();
  FollowAnalytics.setData("key", "value"); // To save and persist string data.
  FollowAnalytics.getData("key"); // To retrieve a previously saved string data from its key.
  

• Logging events/errors/locations:

  FollowAnalytics.logEvent("anEventName");
  FollowAnalytics.logEvent("anEventName", 1);
  FollowAnalytics.logEvent("anEventName", "anEventDetail");
  FollowAnalytics.logEvent('anEventName', {'anEventKey':'anEventValue'})
  FollowAnalytics.logError("anErrorName");
  FollowAnalytics.logError("anErrorName", 1);
  FollowAnalytics.logError("anErrorName", "anErrorDetail");
  FollowAnalytics.logError("anErrorName", {'anEventKey':'anEventValue'})
  FollowAnalytics.logLocation(48.8410646, 2.3210844);
  

• User attributes:

  FollowAnalytics.UserAttributes.setFirstName("aFirstName");
  FollowAnalytics.UserAttributes.setLastName("aLastName");
  FollowAnalytics.UserAttributes.setEmail("something@domain.com");
  FollowAnalytics.UserAttributes.setDateOfBirth(new Date("1998-08-01"));
  FollowAnalytics.UserAttributes.setGender(FollowAnalytics.Gender.MALE); // Can be MALE, FEMALE or OTHER
  FollowAnalytics.UserAttributes.setCountry("France");
  FollowAnalytics.UserAttributes.setCity("Paris");
  FollowAnalytics.UserAttributes.setRegion("Île-de-France");
  FollowAnalytics.UserAttributes.setProfilePictureUrl("https://picture_url");
  FollowAnalytics.UserAttributes.setNumber("aKey", 10.5);
  FollowAnalytics.UserAttributes.setDateTime("aKey", Date.now());
  FollowAnalytics.UserAttributes.setDate("aKey", Date.now());
  FollowAnalytics.UserAttributes.setString("aKey", "aString");
  FollowAnalytics.UserAttributes.setBoolean("aKey", true);
  FollowAnalytics.UserAttributes.addToSet("aSetKey", "aSetElement");
  FollowAnalytics.UserAttributes.removeFromSet("aSetKey", "aSetElement");
  FollowAnalytics.UserAttributes.clear("aKey");
  FollowAnalytics.UserAttributes.clearSet("aSetKey");
  

• InApp campaigns archiving:

  FollowAnalytics.InApp.markAsRead(['campaignId1', 'campaignId2'/*,..., 'campaignIdN'*/]);
  FollowAnalytics.InApp.markAsUnread(['campaignId1', 'campaignId2'/*,..., 'campaignIdN'*/]);
  FollowAnalytics.InApp.delete(['campaignId1', 'campaignId2'/*,..., 'campaignIdN'*/]);
  FollowAnalytics.InApp.get("aCampaignId"); // Returns an campaign Message json object as a String
  FollowAnalytics.InApp.getAll(); // Returns an array of campaign Message json object as a String
  

• Push campaigns archiving:

  FollowAnalytics.Push.markAsRead(['campaignId1', 'campaignId2'/*,..., 'campaignIdN'*/);
  FollowAnalytics.Push.markAsUnread(['campaignId1', 'campaignId2'/*,..., 'campaignIdN'*/]);
  FollowAnalytics.Push.delete(['campaignId1', 'campaignId2'/*,..., 'campaignIdN'*/]);
  FollowAnalytics.Push.get("aCampaignId"); // Returns an campaign Message json object as a String
  FollowAnalytics.Push.getAll(); // Returns an array of campaign Message json object as a String
  

• Badge:

  FollowAnalytics.Badge.set(1); // To update the app icon badge when Notifications are authorized with with badge.
  FollowAnalytics.Badge.updateBy(1); // To increment the value of the app icon badge when Notifications are authorized with with badge.
  

Disabling Swizzling

By default, the SDK swizzles methods from your UIApplicationDelegate, your UNUserNotificationCenterDelegate, and from your UISceneDelegate if your project is configured with it. Along with the swizzled UISceneDelegate methods our SDK observes the scene lifecycle notifications. 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:

   Forward this method if your projects don't implement the UISceneDelegate protocol. 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:

   Forward this method if your projects don't implement the UISceneDelegate protocol. 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:

   Forward this method if your projects don't implement the UISceneDelegate protocol. 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 will allow the application to present an alert providing the current device 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 will allow the application to present an alert providing the current device 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 will allow the application to present an alert providing the current device 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)
   }
   

And if your project implements the UISceneDelegate the required methods to forward are:

1. willConnectToSession::

   Objective-C

   + (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
     [FollowAnalytics scene:scene willConnectToSession:session options:connectionOptions];
   }
   

   Swift

   func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
     FollowAnalytics.scene(scene, willConnectTo: session, options: connectionOptions)
   }
   

2. sceneDidEnterBackground::

   Objective-C

   - (void)sceneDidEnterBackground:(UIScene *)scene {
     [FollowAnalytics sceneDidEnterBackground:scene];  
   }
   

   Swift

   func sceneDidEnterBackground(_ scene: UIScene) {
     FollowAnalytics.sceneDidEnterBackground(scene)  
   }
   

3. sceneWillEnterForeground::

   Objective-C

   - (void)sceneWillEnterForeground:(UIScene *)scene {
     [FollowAnalytics sceneWillEnterForeground:scene];  
   }
   

   Swift

   func sceneWillEnterForeground(_ scene: UIScene) {
     FollowAnalytics.sceneWillEnterForeground(scene)  
   }
   

4. sceneDidBecomeActive::

   Objective-C

   - (void)sceneDidBecomeActive:(UIScene *)scene {
     [FollowAnalytics sceneDidBecomeActive:scene];  
   }
   

   Swift

   func sceneDidBecomeActive(_ scene: UIScene) {
     FollowAnalytics.sceneDidBecomeActive(scene)  
   }
   

5. openURLContexts::

   Objective-C

   - (void) scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
     [FollowAnalytics scene:scene openURLContexts:URLContexts];
   }
   

   Swift

   func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
     FollowAnalytics.scene(scene, openURLContexts: URLContexts)
   }
   

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: