API Reference
Log In

This section describes how to configure MOCA iOS SDK in your app.

Location Services

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.

KeyType
NSLocationAlwaysUsageDescriptionStringThis app will use your location information to identify ,nearby places and to notify you about available proximity experiences.
NSLocationAlwaysAndWhenInUseUsageDescriptionStringAlways location permission is needed in order to detect bluetooth beacons and geofences
NSLocationWhenInUseUsageDescriptionStringWhen app is in use location permission will be used to notify you about relevant content around your location

❗️

Important

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.

Requesting permissions on runtime

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.

Enable or disable SDK auto permission request

In the MOCAConfig.plist

Key name: LOCATION_PERMISSION_REQUEST_MODE
Possible values:

  • 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.

Key name: REQUEST_NOTIFICATIONS_PERMISSION
Possible values:

  • 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(true);
MOCA.setProximityEnabled(true);
[MOCA setGeoTrackingEnabled:YES];
[MOCA setProximityEnabled:YES];

App Transport Security

App Transport Security

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 info.plist:
Bear in mind you can use the key description (see image) instead of the key (NS...).

438

Using key's descriptions.

500

Universal Links Support

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:

Key: MOCA_UNIVERSAL_KEY_DOMAINS
Type: Array
Value: [Array of Domains]

Example:

1272

Custom Deep Link Navigator Support

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];

Custom URL Schemes for Deep Linking

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.

App Capabilities

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
817

❗️

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.

App Keys

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.
  • Get App Key and App Secret.
704

App keys in MOCA Console

🚧

Environment

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.

SDK Configuration File

Now, you’ll need to prepare SDK configuration file:

  • Go back to your Xcode project.
  • CocoaPods only: You will find the MOCAConfig.plist in the following path: Pods/MOCA/Resources there is no need to add it manually
261
KeyTypeDefault ValueDescription
APP_KEYStringApp key from MOCA Console
APP_SECRETStringApp secret from MOCA Console
LOG_LEVELString"info"MOCA SDK logging level:
trace
debug
info
warn
* error
CACHE_DISK_SIZE_IN_MBInteger100Maximum local disk space available for SDK cache.
AUTOMATIC_PUSH_SETUP_ENABLEDBOOLYESIf enabled, the SDK will automatically subscribe the app to APNS (Apple push notification service) and obtain push token.
PROXIMITY_SERVICE_ENABLEDBOOLYESEnables or disables Bluetooth Beacon monitoring and ranging & geofence detection using iOS Location Services
GEOLOCATION_SERVICE_ENABLEDBOOLYESEnables/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_KEY and APP_SECRET values with the real values for your app which you found in the MOCA console.
949

Sample MOCAConfig.plist file.

Other MOCAConfig.plist settings

Key: OVERLAY_DELAY_ON_STARTUP_SECONDS
Type: NUMBER
Default value: 3

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.