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 and NSLocationWhenInUseUsageDescription 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

Register with neccessary methods.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    if ([application respondsToSelector:@selector(isRegisteredForRemoteNotifications)]) {
        if (@available(iOS 10.0, *)) {
            UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
            [center requestAuthorizationWithOptions:(UNAuthorizationOptionAlert + UNAuthorizationOptionSound + UNAuthorizationOptionBadge) completionHandler:^(BOOL granted, NSError * _Nullable error) {
                if (!granted) {
                    // print error content
                }
            }];
        } else {
            // Fallback on earlier versions iOS 9.0
            [[UIApplication sharedApplication] registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:(UIUserNotificationTypeSound | UIUserNotificationTypeAlert | UIUserNotificationTypeBadge) categories:nil]];
            [[UIApplication sharedApplication] registerForRemoteNotifications];
        }
    }
    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)

- (void)application:(UIApplication *)application didReceiveLocalNotification:(nonnull UILocalNotification *)notification {
    NSString *action = nil;
    PCActionType actionType = Notification;
    if (notification.userInfo) {
        action = [PCEnums getActionUuid: notification.userInfo];
        actionType = [PCEnums getActionType: notification.userInfo];
    }
    UIAlertController *alertController;
    switch (actionType) {
        case Notification: {
            if (application.applicationState == UIApplicationStateActive) {
                alertController = [UIAlertController alertControllerWithTitle:notification.alertTitle
                                                                      message:notification.alertBody
                                                               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:^{
                }];
            } else if (action) {
                [[PCManager sharedManager] reportConversion:kPCConversionSuccessful forCampaignAction:[action copy]];
            }
            break;
        }
        case Website:
        case DeepLink: {
            NSString *urlString = [notification.userInfo valueForKey:@"url"];
            NSURL *URL = [NSURL URLWithString:urlString];
            if (application.applicationState == UIApplicationStateActive) {
                alertController = [UIAlertController alertControllerWithTitle:notification.alertTitle
                                                                      message:notification.alertBody
                                                               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]];
                                                               }
                                                               [application openURL:URL options:@{}
                                                                  completionHandler:^(BOOL success) {
                                                                  }];
                                                           }];
                UIAlertAction *cancel = [UIAlertAction actionWithTitle:@"Cancel"
                                                                 style:UIAlertActionStyleCancel
                                                               handler:^(UIAlertAction *_Nonnull action) {
                                                               }];
                [alertController addAction:ok];
                [alertController addAction:cancel];

                [[self.window rootViewController] presentViewController:alertController animated:YES completion:^{
                }];
                // when notification received in background
            } else {
                // report conversion: "notification clicked"
                if (action) {
                    [[PCManager sharedManager] reportConversion:kPCConversionSuccessful forCampaignAction:[action copy]];
                }
                [application openURL:URL options:@{}
                   completionHandler:^(BOOL success) {
                       NSLog(@"Open %@: %d", urlString, success);
                   }];
            }
            break;
        }
    }
}

IDFA Support

  • Implement AdSupport library (details here) to enable support for IDFA collection

  • Pass the IDFA value to SDK using setIDFAvalue():

      if let aaid = ASIdentifierManager.shared().advertisingIdentifier {
          DDLogInfo("Successfully get AAID: \(aaid.uuidString)")
              PCManager.shared().setIDFAValue(aaid.uuidString)
              } else {
          DDLogWarn("Error with getting advertisingIdentifier, should check AAID later")
      }
    

Further information

For more information and support contact us at support@proxi.cloud.

Dependencies

The proxi.cloud SDK 2.x.x requires iOS 9.0 and uses: