Integrate IOS SDK (Obj-C)
This is a guide to help developers get up to speed with proxi.cloud iOS SDK. These step-by-step instructions are written for Objective-C developers. For instructions in Swift please click here.
Remember to set-up your application in the panel before integrating the SDK into your app. Go to https://panel.proxi.cloud and generate an API key for your app.
Demo app
Run pod try ProxicloudSDK
in a terminal will open the proxi.cloud demo project.
Select the PCDemoApp
target and run on device.
Alternatively you can access to the repository here.
Quickstart
Cocoapods
The easiest way to integrate the iOS SDK is via CocoaPods. If you’re new to CocoaPods, visit their getting started documentation.
cd your-project-directory
pod init
open -a Xcode Podfile
Once you’ve initialized CocoaPods, just add the proxi.cloud pod to your target:
target 'YourApp' do
pod 'ProxicloudSDK'
end
Now you can install the dependencies in your project:
pod install
open <YourProjectName>.xcworkspace
Using the SDK
Import the ProxicloudSDK
# import <ProxicloudSDK/ProxicloudSDK.h>
# import <UserNotifications/UserNotifications.h>
Setup the PCManager with an API key and a delegate
You can find your API key on the proxi.cloud panel in the “Apps” section.
The proxi.cloud SDK uses an event bus for events dispatching.
During setup, you pass the class instance that will receive the events as the delegate
.
[[PCManager sharedManager] setApiKey:kAPIKey delegate:self];
Before starting the scanner, we need to ask permission to use the Location services.
If you want to receive events while the app is innactive, you need to pass YES
to the requestLocationAuthorization
. If you pass NO
, the app will receive events only when active.
[PCManager sharedManager] requestLocationAuthorization:YES];
Important
Be sure to add the
NSLocationAlwaysAndWhenInUseUsageDescription
NSLocationAlwaysUsageDescription
andNSLocationWhenInUseUsageDescription
key to your plist file and the corresponding string to explain to the user why the app requires access to location.You need also to enable the Access WiFi Information capability for your app in Xcode.
Now, we can start the SDK preferably in the location authorisation callback
SUBSCRIBE(PCEventLocationAuthorization)
{
if (event.locationAuthorization==.authorized)
{
[[PCManager sharedManager] startMonitoring];
}
}
Start receiving push notifications
Add UNUserNotificationCenterDelegate
protocol to AppDelegate and register with neccessary methods
// AppDelegate.h
@interface AppDelegate : UIResponder <UIApplicationDelegate, UNUserNotificationCenterDelegate>
//AppDelegate.m
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
center.delegate = self;
[center requestAuthorizationWithOptions:(UNAuthorizationOptionAlert + UNAuthorizationOptionSound + UNAuthorizationOptionBadge) completionHandler:^(BOOL granted, NSError *_Nullable error) {
if (!granted) {
// print error content
}
}];
return YES;
}
Action types
SDK support three action types: notification, website and deeplink. You can perform a different action for each of them in AppDelegate
method (switch statement contains sample actions)
// This function will be called if user receive notification in foreground
- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler{
NSString *action = nil;
PCActionType actionType = Notification;
if (notification.request.content.userInfo) {
action = [PCEnums getActionUuid: notification.request.content.userInfo];
actionType = [PCEnums getActionType: notification.request.content.userInfo];
}
UIAlertController *alertController;
switch (actionType) {
case Notification: {
alertController = [UIAlertController alertControllerWithTitle:notification.request.content.title
message:notification.request.content.body
preferredStyle:UIAlertControllerStyleAlert];
UIAlertAction *ok = [UIAlertAction actionWithTitle:@"OK"
style:UIAlertActionStyleDefault
handler:^(UIAlertAction *_Nonnull actionHandler) {
// report conversion: "notification clicked"
if (action) {
[[PCManager sharedManager] reportConversion:kPCConversionSuccessful forCampaignAction:[action copy]];
}
}];
[alertController addAction:ok];
[[self.window rootViewController] presentViewController:alertController animated:YES completion:^{
}];
}
case Website:
case DeepLink: {
NSString *urlString = [notification.request.content.userInfo valueForKey:@"url"];
NSURL *URL = [NSURL URLWithString:urlString];
alertController = [UIAlertController alertControllerWithTitle:notification.request.content.title
message:notification.request.content.body
preferredStyle:UIAlertControllerStyleAlert];
UIAlertAction *ok = [UIAlertAction actionWithTitle:@"OK"
style:UIAlertActionStyleDefault
handler:^(UIAlertAction *_Nonnull actionHandler) {
// report conversion: "notification clicked"
if (action) {
[[PCManager sharedManager] reportConversion:kPCConversionSuccessful forCampaignAction:[action copy]];
}
[[UIApplication sharedApplication] openURL:URL options:@{} completionHandler:nil];
}];
UIAlertAction *cancel = [UIAlertAction actionWithTitle:@"Cancel"
style:UIAlertActionStyleCancel
handler:nil];
[alertController addAction:ok];
[alertController addAction:cancel];
[[self.window rootViewController] presentViewController:alertController animated:YES completion:^{
}];
}
}
}
// This function will be called right after user tap on the notification
- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler{
NSString *action = nil;
PCActionType actionType = Notification;
if ( response.notification.request.content.userInfo) {
action = [PCEnums getActionUuid: response.notification.request.content.userInfo];
actionType = [PCEnums getActionType: response.notification.request.content.userInfo];
}
switch (actionType) {
case Notification: {
[[PCManager sharedManager] reportConversion:kPCConversionSuccessful forCampaignAction:[action copy]];
break;
}
case Website:
case DeepLink: {
NSString *urlString = [response.notification.request.content.userInfo valueForKey:@"url"];
NSURL *URL = [NSURL URLWithString: urlString];
// report conversion: "notification clicked"
if (action) {
[[PCManager sharedManager] reportConversion:kPCConversionSuccessful forCampaignAction:[action copy]];
}
[[UIApplication sharedApplication] openURL:URL options:@{} completionHandler:nil];
}
}
}
IDFA Support
- Add imports
#import <AdSupport/ASIdentifierManager.h> #import "AppTrackingTransparency/AppTrackingTransparency.h"
-
Add to info.plist
NSUserTrackingUsageDescription
key and usage-description string, which displays as a system-permission alert request. The usage-description string tells the user why the app is requesting permission to use data for tracking the user or the device. -
Ask for permission and pass the IDFA value to SDK using:
if (@available(iOS 14, *)) { [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) { if (status == ATTrackingManagerAuthorizationStatusAuthorized) { NSString *idfa = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString]; [[PCManager sharedManager] setIDFAValue:idfa]; } }]; } else { if ([ASIdentifierManager sharedManager].isAdvertisingTrackingEnabled){ NSString *idfa = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString]; [[PCManager sharedManager] setIDFAValue:idfa]; } }
Reporting custom events
Starting from v2.1.x the SDK allows to report custom events which then can be agreggated and analysed in the proxi.cloud platform. To use this functionality simply call the ReportEvent method when the event you wish to report occurs. The SDK will automatically add current timestamp and location (if it can be established) to the event and send it back to the proxi.cloud platform for further aggregation where it can be used to create custom reports and analytics. Below is an example showing how to report particular product view within the app.
[[PCManager sharedManager] reportEvent:@"product_viewed" withValue:@"Awesome Product 500g"];
Instant push messages via Firebase Cloud Messaging
-
Add Notification Service Extension to xCode project Details here
-
Create provisioning profile for extensions bundle identifier
- Add new target in Podfile
target 'yourNotificationServiceExtensionName' do pod 'Firebase/Messaging' end
- Install the dependencies in your project:
pod install
- Modify function in created extension
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler { self.contentHandler = contentHandler; self.bestAttemptContent = [request.content mutableCopy]; if ([self.bestAttemptContent.userInfo valueForKey:@"eid"]){ NSMutableDictionary *userInfo = [request.content.userInfo mutableCopy]; UNMutableNotificationContent *content = [request.content mutableCopy]; [userInfo setObject:[NSUUID UUID].UUIDString forKey:@"action"]; [userInfo setObject:@"proxi_fcm" forKey:@"sender_id"]; content.userInfo = userInfo; self.bestAttemptContent = content; } [[FIRMessaging extensionHelper] populateNotificationContent:self.bestAttemptContent withContentHandler:contentHandler]; }
and add
@import Firebase;
- Modify User notifications center dalegate functions
- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler{ // add this line [[PCManager sharedManager] passResponseToPcSdkForNotification:notification]; } - (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void(^)(void))completionHandler{ // add this line [[PCManager sharedManager] passResponseToPcSdkForNotification:response.notification]; }
Further information
For more information and support contact us at [email protected].
Dependencies
The proxi.cloud SDK 2.x.x requires iOS 10.0 and uses:
- JSONModel version 1.1 for JSON parsing
- UICKeyChainStore version 2.0 for keychain access
- tolo version 1.0.1 for event communication
- objc-geohash version 0.0.2 for geocoding system