Skip to content

Contextual (iOS 15+) Setup

You can find an example of integration here

Prerequisites

  • Deployment target iOS 15.0 and above.
  • Xcode 13.4.1 or above.


Note

If using an Apple Silicon Mac, you will likely need to use a Rosetta terminal when installing dependencies or at least prefix your terminal commands with "arch -x86_64".

e.g. arch -x86_64 pod update


This setup assumes you have already setup your App Key on the Dashboard.

See prerequisites.

CocoaPods

Step 1 - Pod File

In pod file of your Application, add the following line:

1
2
3
platform :ios,'15.0' # or above

pod "Contextual"

Step 2 - Install

On the first time, run:

1
pod install

For updates and ensuring to get the latest version of the Contextual SDK, run: 

1
pod update
This installs Contextual binary and dependencies.

Note

If you have used cocoapods previously, please run either "pod update" or "pod update Contextual --no-repo-update", this will ensure that the most recent version of the Contextual SDK is integrated.

Swift Package Manager

Step 1 - Add Package Dependency

Add Contextual SDK as a Swift Package Manager dependency

1
https://github.com/contextu-al/Contextual-SDK

For Version Rules, you can use:

1
Branch -> main
To ensure that you always have the latest, or alternatively you can use:

1
Version -> Up To Next Major -> 3.0.0 < 4.0.0
To ensure that you always have the latest 3.x version

Integration Steps

Step 1 - Register an install during app launch

In your Application launch function, add Contextual registration.

Import the Contextual SDK:

Swift 
1
import ContextualSDK

Objective-C 
1
#import "ContextualSDK/ContextualSDK.h"

If you are using Swift, add the following code in AppDelegate:

Swift 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate
{
    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

        // Replace 'MyApp' with your app_key, registered in the Contextual Dashboard.
        // Set 'withDebugMode' to 'true' to enable debug logging.
        Contextual.sharedInstance().registerInstall(forApp: appKey, withDebugMode: false) {
            Contextual.sharedInstance().tagUserId("user@example.com")
        }

        return true
    }
}
If you are using ObjectiveC, add the following code in AppDelegate:

Note

React Native users - make sure the #import "ContextualSDK/ContextualSDK.h" is above the #if DEBUG or #ifdef FB_SONARKIT_ENABLED declaration (if present)

Objective-C 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
#import "ContextualSDK/ContextualSDK.h"

#ifdef FB_SONARKIT_ENABLED // IMPORTS MUST GO ABOVE THIS DECLARATION
#import <FlipperKit/FlipperClient.h>
#import <FlipperKitLayoutPlugin/FlipperKitLayoutPlugin.h>
#import <FlipperKitUserDefaultsPlugin/FKUserDefaultsPlugin.h>
#import <FlipperKitNetworkPlugin/FlipperKitNetworkPlugin.h>
#import <SKIOSNetworkPlugin/SKIOSNetworkAdapter.h>
#import <FlipperKitReactPlugin/FlipperKitReactPlugin.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Replace 'MyApp' with your app_key, registered in the Contextual Dashboard.
    // Set 'withDebugMode' to 'YES' to enable debug logging.
    [CONTEXTUAL registerInstallForApp:@"MyApp" withDebugMode:NO completion:^{
        [CONTEXTUAL tagUserId:[NSString stringWithFormat:@"user@example.com"]];
    }];

    return YES;
}

Step 2 - Replace Base Classes

iOS Native

UIKit

Replace the base ViewController classes and inherit from Contextual SDK classes as shown below.

From To
UITableViewController ContextualBaseTableViewController
UIViewController ContextualBaseViewController
UICollectionViewController ContextualBaseCollectionViewController

Swift UI

If you are using primarily Swift UI for your screens and views, then you will need to implement the UIViewControllerRepresentable protocol on your Swift UI View that is being used as a screen.

Example:

If you have a Swift UI View named "TicketListViewVC" that is acting as a screen for your app, then you should implement the UIViewControllerRepresentable protocol as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
struct TicketListViewVC: UIViewControllerRepresentable {
  func updateUIViewController(_ uiViewController: UIViewControllerType, context: Context) {
  }

  func makeUIViewController(context: Context) -> some UIViewController {
    Contextual.sharedInstance().setReactViewName("TicketList Screen")
    let baseVC = ContextualBaseViewController()
    let viewVC = UIHostingController(rootView: TicketListView())
    baseVC.addChild(viewVC)
    baseVC.view.addSubview(viewVC.view)
    viewVC.view.frame = UIScreen.main.bounds
    viewVC.didMove(toParent: baseVC)
    return baseVC
  }

  func makeCoordinator() -> () {
  }
}

!!! note For a sample project to see how the Contextual SDK was implemented into a Swift UI project, see: https://github.com/contextu-al/FlightTicketBrowser

React Native

In your AppDelegate.m where the rootViewController is created, replace UIViewController with ContextualBaseViewController

React Native < v0.71.0:

1
2
3
4
5
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  // Replace UIViewController with ContextualBaseViewController
  UIViewController *rootViewController = [ContextualBaseViewController new];
}

React Native >= v0.71.0:

There is a new delegate method for customising the root view, so implementat that and specify the base class for the View Controller:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- (UIView *)createRootViewWithBridge:(RCTBridge *)bridge
                          moduleName:(NSString *)moduleName
                           initProps:(NSDictionary *)initProps
{
  UIView * rootView = [super createRootViewWithBridge:bridge moduleName:moduleName initProps:initProps];

  UIViewController *rootViewController = [ContextualBaseViewController new];
  rootViewController.view = rootView;
  self.window.rootViewController = rootViewController;

  return rootView;
}

Info

If your view controller overrides system functions, make sure you call super.

Note

Replacing your view controller with the Contextual controller is essential for Contextual to function correctly. Please ensure that if you have multiple view controllers showing on the same screen to replace the base ViewController in each of the UIViewController subclasses (child ViewControllers)

Step 3 - Set sh_cuid [Optional]

We recommend you also send a unique ID for the user so you can "tag" users from your backend system. This is called the sh_cuid.

If you would like to tag the user during registration just place the following snippet.

Swift 
1
2
3
4
// Unique id in your system, for example customer's login ID
Contextual.sharedInstance().registerInstall(forApp: "MyApp", withDebugMode: false) {
    Contextual.sharedInstance().tagUserId("user@example.com")
}

Objective-C 
1
2
3
4
// Unique id in your system, for example customer's login ID
[CONTEXTUAL registerInstallForApp:@"MyApp" withDebugMode:NO completion:^{
    [CONTEXTUAL tagUserId:@"user@example.com"];
}];

If you would like to tag the user at any other place in your application eg after login call, just place the following snippet.

Swift 
1
2
// Unique id in your system, for example customer's login ID
   Contextual.sharedInstance().tagUserId("user@example.com")

Objective-C 
1
2
// Unique id in your system, for example customer's login ID
    [CONTEXTUAL tagUserId:@"user@example.com"];
Last update: 2024-01-15