Declare the following permissions in case you want to use the Geofencing and Bluetooth Beacon detection features of the platform in your
Info.plist file. Customize the text with an appropriate wording for your context and application.
|NSLocationAlwaysUsageDescription||String||This app will use your location information to identify ,nearby places and to notify you about available proximity experiences.|
|NSLocationAlwaysAndWhenInUseUsageDescription||String||Always location permission is needed in order to detect bluetooth beacons and geofences|
|NSLocationWhenInUseUsageDescription||String||When app is in use location permission will be used to notify you about relevant content around your location|
If this key is not present in your
info.plist, iOS Location Services won't start, preventing the App from detecting Bluetooth Beacons, Geofences and from receiving Location updates.
This message will be prompted to the user when asked for location services permission. Please bear in mind that if this key is not present in your info.plist, location services won’t work at all.
MOCA SDK can conveniently request the location and notification permissions for you, out of the box. However, the SDK will ask for the permissions as soon as it is initialized. This means that the user could potentially see too many permission request prompts without understanding the purpose of them and without context. This is the default behavior.
We strongly recommend that your application request these permissions.
auto: Default value. SDK will request the "Always" permission as soon as possible.
WhenInUse: SDK will request the permission "When in Use". This permission limits the ability to detect beacons and geofence in the background.
Disabled: MOCA SDK won't request location permissions.
Yes: Default value. SDK will request the permission on SDK initialization.
No: SDK will not request the permission.
NOTE: If you choose the
Disabled option. Call the following methods as soon as the user grants you the permission:
[MOCA setGeoTrackingEnabled:YES]; [MOCA setProximityEnabled:YES];
iOS 9 blocks all non-HTTPS requests, as you probably may want to show content hosted in non-HTTPS servers, please add the following keys to your
Bear in mind you can use the key description (see image) instead of the key (NS...).
Using key's descriptions.
In order to use Universal Links within MOCA Campaigns. (e.g. Once a user clicks on a notification, it opens a specific screen of your app using a universal link), you need to declare the domains your application support in the SDK
MOCAConfig.plist as follows:
Value: [Array of Domains]
MOCA SDK v3.7.0+ supports navigator delegate protocol and handler. With this you'll be able to receive the payload and pass it on to your custom deep link handler.
/** * MOCA navigator protocol to be implemented by custom deep link handler. */ @protocol MOCANavigatorHandler <NSObject> // Called when a deep link has been triggered from MOCA SDK. // If implemented, the delegate is responsible for processing the provided // url. It must return TRUE to indicate the link was processed. // When it returns FALSE, the MOCA SDK executes the standard deep-link // behavior. - (BOOL)handleDeepLink:(nonnull NSURL *)url completionHandler:(nonnull void (^)(void))completionHandler; @end
In order to customize the handling of the deep links in your app, implement this protocol in
your Delegate class and register it before initializing SDK.
// Register handler before MOCA SDK initialized to handle all events both on // launch and later. MOCA.navigatorHandler = self; [MOCA initializeSDK:config];
If your app uses custom URL schemes, MOCA SDK supports it out of the box. For example fb://home will take you to the facebook home page.
MOCA SDK requires the app to enable selected Capabilities. Open XCode with your app project, go to Target, and select Capabilities configuration page.
First, within Background Modes section, ensure the following entitlements are enabled:
- Background Fetch
- Remote Notifications
Do not select Location updates (unless you need it for another App feature). MOCA SDK does not require this mode. If you enable it and do not use it for any purpose, your App will be rejected by Apple.
To link you app to your MOCA account, you must register the app in the MOCA Console and add corresponding AppKey and AppSecret.
- Goto https://console.mocaplatform.com and sign in to your MOCA account.
- Select Apps item at left sidebar, and then click + New App in the content panel or select your existing App.
- Navigate to Settings item. Select API keys tab.
We highly recommend creating at least two apps: A "Development" version, and a "Production" version. Select the appropriate environment in the settings (Prod or Dev).
The MOCA environment determines whether if the remote notifications are sent via APNS dev or prod servers.
Now, you’ll need to prepare SDK configuration file:
- Go back to your Xcode project.
CocoaPodsonly: You will find the MOCAConfig.plist in the following path:
Pods/MOCA/Resourcesthere is no need to add it manually
- Add New file / Property List resource to your project. Save it as MOCAConfig.plist file. (optional, download sample MOCAConfig.plist file)
- Add configuration settings as shown below.
|APP_KEY||String||App key from MOCA Console|
|APP_SECRET||String||App secret from MOCA Console|
|LOG_LEVEL||String||"info"||MOCA SDK logging level:|
|CACHE_DISK_SIZE_IN_MB||Integer||100||Maximum local disk space available for SDK cache.|
|AUTOMATIC_PUSH_SETUP_ENABLED||BOOL||YES||If enabled, the SDK will automatically subscribe the app to APNS (Apple push notification service) and obtain push token.|
|PROXIMITY_SERVICE_ENABLED||BOOL||YES||Enables or disables Bluetooth Beacon monitoring and ranging & geofence detection using iOS Location Services|
|GEOLOCATION_SERVICE_ENABLED||BOOL||YES||Enables/disables tracking of significant changes in user location by GPS/Cellular Trilateration/Wifi.|
When enabled (YES), user location will be tracked when the app is in foreground. Additionally, background tracking is controlled by BACKGROUND_LOCATION_ENABLED flag. This is the default.
When disabled (NO), user location will not be tracked at all (neither in foreground nor on background). However, Bluetooth beacons and geofences will still be detected if this flag is set to NO.
MOCA performs location tracking using low battery usage modes to save battery life. For example, when the app is in background GPS-quality tracking is never used.
- Be sure to replace
APP_SECRETvalues with the real values for your app which you found in the MOCA console.
Some MOCA Campaigns consist of two parts:
- A notification
- An overlay that is shown on top of the application once the user taps on the notification.
If the application is not running when the user taps on the notification, the SDK will wait
OVERLAY_DELAY_ON_STARTUP_SECONDS seconds before attempting to show the content as an overlay.
If your application tends to take more time to start up. Change this setting accordingly.