Getting Started with iOS SDK

Requirements

  • Xcode 7 and above
  • iOS 7.0 and above

Installing the SDK

Bitcode

There is both a bitcode enabled and bitcode disabled version of Neumob. To distinguish whether a version of Neumob has bitcode enabled, check the last digit of the release version.

Ex.
x.x.x.1 -> Bitcode Enabled = No
x.x.x.2 -> Bitcode Enabled = Yes

To determine whether your application has bitcode enabled, navigate to your project and check the Enable Bitcode property in your Build Settings under Build Options.

../_images/bitcode_setting.png

CocoaPods

If you use CocoaPods, add one of following line to your project’s podfile and run pod install or pod update.

pod 'Neumob'

The latest version pulled through CocoaPods will be built with bitcode enabled. Should you wish to have a bitcode disabled version, please find the latest Neumob release and append a 1 instead of 2.

Note

Ex.
pod ‘Neumob’, ‘3.5.2.1’ // Xcode 7 - Bitcode not enabled
pod ‘Neumob’, ‘3.5.2.2’ // Xcode 7 - Bitcode enabled

Manual installation (Drag and drop)

1. Download and unzip the iOS SDK. You can find under a download link under your App settings. There should be a bitcode enabled and bitcode disabled version of the SDK.

../_images/ios_portal_sdk_download.png
  1. Drag Neumob.framework into your Xcode project.

3. Link with SystemConfiguration.framework, CoreTelephony.framework, and libresolve.9.tbd (Xcode 7+) or libresolv.9.dylib (Xcode 6 and below). We use SystemConfiguration and CoreTelephony to optimize Neumob configurations for your network and to respond to any changes that may occur. We use libresolv for DNS related functions.

Initializing Neumob

Initialization is the process of modifying your application in order to communicate with Neumob. To use Neumob, you’ll have to import the Neumob header into your AppDelegate’s implementation file. For Swift applications, place this import in your bridging-header.h file.

// AppDelegate.m (Obj-C) or bridging-header.h (Swift)
#import <Neumob/Neumob.h>

Initialize Neumob only once on the main thread at the beginning of your AppDelegate’s application:didFinishLaunchingWithOptions: method.

// Objective C
[Neumob initialize:@"NEUMOB_CLIENT_KEY"];
// Swift
Neumob.initialize("NEUMOB_CLIENT_KEY");

Your client key can be retrieved on the portal by registering an application.

Neumob is now integrated with your iOS application! In order to turn ON Neumob for your app version you’ll go to the portal’s app details page where you received your client key. The State for the app version will be OFF and this can be changed by clicking the settings button under Action, toggling the switch in the upper right corner of the following screen, and then the Apply button at the bottom.

Note

Neumob takes about 2 days to learn, customize, and then accelerate you network calls.

Verifying Integration

To check that Neumob is initialized and whether an app session is being accelerated, you can add a completionHandler parameter that will execute after initialize is completed. Because init can be asynchronous, checking accelerated and related API outside of the completionHandler may return inconsistent values.

initialized returns a boolean indicating Neumob is enabled and ready to accelerate your network requests.

accelerated returns a boolean indicating whether Neumob is currently accelerating your requests. You may configure whether or not Neumob is accelerated by adjusting the % accelerated slider through the portal (click the settings button for the app version on your app details page). If you plan to A / B test accelerated vs unaccelerated Neumob sessions, we recommend using the accelerated API in the completionHandler. Please note that accelerated is sticky- meaning a user who is accelerated will remain accelerated until the % accelerated slider value is changed.

The accelerated boolean value can be used to populate a property or dimension within your mobile analytics platform.

Here’s an example of how you might verify Neumob initialization and check whether a session is accelerated.

// Objective C
[Neumob initialize:@"NEUMOB_CLIENT_KEY" completionHandler:^{
     if ([Neumob initialized]) {
         // Neumob is ON.
         BOOL accelerated = [Neumob accelerated];
         // ex. [Analytics logCustomDimension: Dimension.ACCELERATION value: accelerated];
         ...
     } else {
         // Neumob is OFF. Change log settings for more details.
         ...
     }
}];
// Swift
Neumob.initialize("NEUMOB_CLIENT_KEY", completionHandler: {
     if (Neumob.initialized()) {
         // Neumob is ON.
         boolean accelerated = Neumob.accelerated();
         // ex. Analytics.logCustomDimension(Dimension.ACCELERATION, accelerated);
         ...
     } else {
         // Neumob is OFF. Change log settings for more details.
         ...
     }
})

Note

At this time, we do not recommend executing your own initialization code inside the runnable block.

Disabling Neumob

If for any reason you are looking to disable Neumob, navigate to the portal to your app settings and select the combination of application versions and/or Neumob SDK versions that should be enabled. Once disabled, Neumob will not initialize on the client device.

../_images/disable_neumob.png

Considerations

1. The Neumob iOS SDK has a native dependency which causes the Xcode debugger to stop on SIGPIPEs. These SIGPIPEs will not negatively affect your application and you can ignore them by adding a breakpoint with the debugger command process handle SIGPIPE -n false -s false

../_images/ios_debugger_settings.png

2. The Neumob iOS SDK uses and registers a custom NSURLProtocol and you can select which hosts you wish for Neumob to accelerate and not to accelerate by implementing a blacklist or whitelist in the portal for your SDK Version and App Version. If you use 3rd party APIs like Google Analytics, we recommend adding those hosts to the blacklist.

  1. The Neumob iOS SDK does not currently support WKWebView requests.