iOS SDK

Overview

Algonomy rCDP Mobile iOS SDK enables you to capture user behavior and clickstream events from native iOS applications. It allows you to track user interactions, manage customer profiles, and deliver personalized experiences such as push notifications and In-App Notifications.

The SDK integrates directly into your application and sends structured event data to rCDP in real time. This ensures that mobile data is unified with web and backend data for a complete customer view.

Note: All SDK integrations follow a standardized event structure (event taxonomy), ensuring consistency across Web, Mobile, and API integrations.

How It Works

  1. The SDK is initialized when the application launches

  2. User interactions are captured as Clickstream Events

  3. Customer data is stored and updated using Customer Profiles

  4. The SDK enriches events with device, session, and app metadata

  5. Events are sent to rCDP for processing and activation

Tip: Initialize the SDK as early as possible to ensure complete session tracking.

SDK Integration

Follow these steps to integrate the rCDP iOS SDK into your application.

Step 1: Add SDK to Project

  1. Download the SDK framework

  2. Add it to your Xcode project

  3. Ensure it is included under the target

Step 2: Configure Permissions

  • Enable Push Notifications

  • Configure App Transport Security if required

  • Enable Background Modes

Step 3: Initialize SDK

Objective-C 


[TargetOne setLogLevel:T1_LL_VERBOSE];
TargetOne *_targetOne = [TargetOne sharedInstance];
T1Config *t1Config = [T1Config new];
t1Config.enableNotification = YES;
t1Config.tenantHash = “YOUR_TENANT_ID”;
[_targetOne initialize:t1Config];

Swift 

TargetOne.setLogLevel(T1_LL_VERBOSE)
let targetOne = TargetOne.sharedInstance()
let t1Config = T1Config()
t1Config.enableNotification = true
t1Config.tenantHash = "YOUR_TENANT_ID"
targetOne?.initialize(t1Config)

Step 4: Verify Integration

  • Trigger a sample event

  • Check logs in Xcode console

  • Verify events in rCDP dashboard

Tip: Validate integration in a test environment before moving to production.

SDK Methods

The iOS SDK supports the following SDK methods:

Customer Profiles

Real-time CDP stores user demographic data, app interactions, campaign visits, and transaction history to build a complete customer profile.

A Customer Profile is automatically created when a user launches your mobile application. Initially, the profile is created as Anonymous, meaning it does not contain identifiable information.

You can enrich the profile with attributes such as Name, Email, Mobile Number, and Customer ID.

Note: Real-time CDP supports both single-value and multi-value profile properties.

Important Notes

  • Set Customer Profile must be called before eventCustomerCreate, eventLogin, and eventLogout

  • If the user logs in before SDK integration, call Set Customer Profile immediately after initialization

Set Customer Profile

Objective-C 

T1CustomerProfile *profile = [T1CustomerProfile new];
profile.custCode = self.txtCustomerCode.text;
profile.emailId = @"sample@mail.com";
profile.mobileNumber = @"9876543210";

[[TargetOne sharedInstance] setCustomerProfile:profile];

Swift 

let profile = T1CustomerProfile()
profile.custCode = "100"
profile.mobileNumber = "9876543210"
profile.emailId = "sample@email.com"

TargetOne.sharedInstance().setCustomerProfile(profile)

Equivalent Payload (JSON) 

{
"customerProfile": {
"custCode": "100",
"emailId": "sample@email.com",
"mobileNumber": "9876543210"
}
}

Tip: Always set the customer profile immediately after user login to ensure accurate identity tracking.

Clickstream Events

A Clickstream Event represents a user action performed within your application. These events are recorded with an event name and associated properties.

This enables segmentation, targeting, and personalization based on user behavior.

Send Clickstream Event

Objective-C 

NSDictionary *props = @{
@"categoryId": @"100"
};

[[TargetOne sharedInstance] sendClickStream:@"eventCategory" withProps:props];

Swift 

let props = [
"categoryId": "100"
]

TargetOne.sharedInstance()?.sendClickStream("eventCategory", withProps: props)

Equivalent Payload (JSON) 

{
"eventName": "eventCategory",
"eventType": "clickstream",
"properties": {
"categoryId": "100"
}
}

Supported Data Types

  • String

  • Number

  • Boolean

  • NSDate (timestamp-based tracking)

Note: Date-based properties can be used for time-based targeting scenarios such as reminders or alerts.

In-App Notifications

In-App Notifications allow you to engage users within the application using contextual messages triggered by user behavior or predefined campaigns.

These notifications are configured from the rCDP console and delivered automatically through the SDK.

Note: In-App Notifications are rendered dynamically and do not require additional UI implementation.

Display In-App Notifications

The SDK automatically displays In-App Notifications based on configured rules and triggers.

Tip: Use behavioral events (such as product views or cart actions) to trigger contextual In-App Notifications.

Block In-App Notifications

You can block In-App Notifications on specific screens where interruptions are not desired.

Objective-C 

[TargetOneSDKContext.blockInApp addObject:@"ViewControllerName"];

Swift 

TargetOneSDKContext.blockInApp.add("ViewControllerName")

Note: Blocking ensures a better user experience in critical flows such as checkout or payments.

Debugging

The SDK provides debugging capabilities to help you validate integration and troubleshoot issues during development.

Enable Debug Mode

Objective-C 

[TargetOne enableDebugMode:YES];

Swift 

TargetOne.enableDebugMode(true)

Tip: Enable debug mode in development environments to view detailed logs in the Xcode console.

Verify Events

  • Check Xcode console logs for SDK activity

  • Validate event payloads

  • Confirm event delivery in the rCDP dashboard

Note: Debug logs include event payloads, API responses, and SDK lifecycle information.

Rich Push Notifications

Rich Push Notifications allow you to send media-rich notifications that include images, buttons, and custom layouts to improve user engagement.

Register Device Token

Register the APNs device token with rCDP to enable push notifications.

Objective-C 

[[TargetOne sharedInstance] registerDeviceToken:deviceToken];

Swift 

TargetOne.sharedInstance().registerDeviceToken(deviceToken)

Handle Push Notification

Handle incoming push notifications from rCDP.

Objective-C 

[[TargetOne sharedInstance] handlePushNotification:userInfo];

Swift 

TargetOne.sharedInstance().handlePushNotification(userInfo)

Tip: Ensure push handling logic is implemented in AppDelegate or notification handlers.

Rich Push Setup (High-Level)

  • Create a Notification Service Extension in Xcode

  • Enable media attachments in push payload

  • Configure payload from rCDP dashboard

Note: Rich Push requires proper APNs configuration and extension setup.

Example Push Payload

{
"aps": {
"alert": {
"title": "Special Offer",
"body": "Get 20% off on your next purchase"
},
"mutable-content": 1
},
"mediaUrl": "https://example.com/image.jpg"
}

APNs Certificate Creation

Apple Push Notification service (APNs) certificates are required to enable push notifications for your iOS application.

Follow these steps to create and configure the APNs certificate:

  1. Log in to the Apple Developer Portal

    2. Navigate to Certificates, Identifiers & Profiles

  2. Select your App ID

  3. Enable Push Notifications

  4. Create a new APNs certificate (Development or Production)

  5. Download the certificate

  6. Convert the certificate to .p12 format

  7. Upload the certificate to the rCDP console

Note: Separate certificates are required for Development and Production environments.

APNs Auth Key Creation

Alternatively, you can use an APNs Auth Key for a more flexible and scalable push notification setup.

Follow these steps to create an APNs Auth Key:

  1. Log in to the Apple Developer Portal

  2. Navigate to Keys

  3. Create a new key with Apple Push Notifications service (APNs) enabled

  4. Download the .p8 key file

  5. Note the following details:

    • Key ID

    • Team ID

    • Bundle ID

  6. Upload the key and details to the rCDP console

Tip: APNs Auth Key is recommended over certificates as it does not expire and supports multiple apps.

Push Notification Flow

  1. User installs and opens the app

  2. Device token is generated and registered with rCDP

  3. Campaign is configured in rCDP

  4. Notification is sent via APNs

  5. SDK receives and displays the notification

Common Use Cases

  • Send personalized offers based on browsing behavior

  • Trigger cart abandonment reminders

  • Deliver transactional notifications (order updates)

  • Engage inactive users with reactivation campaigns

Best Practices

  • Initialize the SDK early in the application lifecycle

  • Use consistent event naming aligned with your event taxonomy

  • Always set customer profile after login

  • Validate event payloads before sending

  • Enable debug mode during development

  • Test push notifications on real devices

  • Use APNs Auth Key for better scalability

  • Ensure compliance with user consent and privacy requirements

Troubleshooting

  • Ensure SDK is initialized correctly

  • Verify API credentials (Tenant ID, API Key)

  • Check network connectivity

  • Validate push notification configuration

  • Check debug logs for errors

Note: Most integration issues are related to incorrect initialization or missing permissions.

Next Steps

  • Proceed to 3.2 Android SDK

  • Proceed to 3.3 React Native SDK