How do I receive MOCA SDK actions in my third party API?

How do I receive MOCA SDK actions in my third party API?

MOCA has a feature called Cloud-Hook. This feature enables the MOCA SDK embedded into the client mobile App to deliver location-triggered actions directly to the Third Party campaigns module and deliver segmented and personalized content to end users.






In order to support the usual business cases, the following location-based triggers are considered within the scope of this feature:

  • Enter geofence - triggered when a user enters a specific geographical location expressed as longitude, latitude and radius in meters. 

  • Exit geofence - triggered when a user leaves the specific geographical location. 

  • Enter beacon - triggered when a user enters into the range of a specific BLE beacon.




The MOCA Cloud-Hook API has the characteristics as described below:

  • HTTPS protocol only

  • OAuth 2.0 authentication scheme

  • UTF-8 encoding

  • The client must include a User-Agent header, Content-Type header and JSON payload.

  • The API provides endpoints and client credentials for both integration and production environments 

  • The API supports a way to identify the calling app. We propose to include APP_KEY request header, for example: 

    • X-App-Key: “yourproject-prod” or similar 

  • The API uses conventional HTTP response codes to indicate success or failure of an API request. 

    • Status 200 - call successful

    • Status 4xx - client errors

    • Status 5xx - internal server errors  

For more details, please refer to https://en.wikipedia.org/wiki/List_of_HTTP_status_codes  


Body Payload field description and example:

Attribute

Data type

Obligatory?

Description

user_id

string

No

Hashed email address provided by App to MOCA SDK when a user signs-in to the mobile app. Not available for not logged-in users.

event_id

string

Yes

Unique event ID (UUID) string.

t

timestamp

Yes

UTC timestamp, in milliseconds, generated by mobile device when the event was first observed. It uses a device clock.

st

timestamp

Yes

UTC timestamp, in milliseconds, generated by MOCA servers when the event was first received in MOCA Cloud. It uses a synchronized server clock.

user_pseudo_id

string

Yes

Unique anonymous user id assigned for each App installed on a device. It is always available.

event_name

string

Yes

Name of generated event. Available options are:

  • enter_geofence

  • exit_geofence

  • enter_beacon

  • enter_region

  • exit_region

geo_category

string

Yes

Geofence, beacon or region.

geo_item

string

Yes

Geofence, beacon or region name

geo_item_id

string

Yes

Geofence, beacon or region unique ID

geo_latitude

double

No

Device current latitude, if available.

geo_longitude

double

No

Device current longitude, if available.

geo_accuracy

double

No

Device current location accuracy, in meters, if available.

device_type

string

Yes

Device type (e.g. iPhone).

device_model

string

Yes

Device model name (e.g. iPhone 11)

os

string

Yes

Device operating system name (e.g. Android)

os_version

string

Yes

Device operating system version (e.g. 14.6)

lang

string

Yes

Device preferred language ISO code

location_status

string

Yes

Location permission status

session

number

Yes

User sequential session number

app_status

string

Yes

Indicates app running status: foreground or background when the event was generated. 

app_version

string

Yes

App version string.

moca_version

string

Yes

MOCA SDK version that generated this event.

dwell_time

long

No

Optional. Dwell time, in seconds, that a user stayed within a geofence or beacon range to trigger this event. By default it is null.

user_properties

JSONObject

No

Optional. A bag of user properties as set by MOCA SDK API.



JSON body = [{

"event_id" : "123e4567-e89b-12d3-a456-426652340000",

"t" : 1626254802012,

"st": 1626254913412,

"user_pseudo_id": "001122334455deeff",

"user_id" : "hashed-email-here",

"event_name" : "enter_beacon",

"geo_category": "beacon",

"geo_item": "store-7-cashier-beacon-1",

"geo_item_id": "e4a7",

"geo_latitude": null,

"geo_longitude": null,

"geo_accuracy": null,

"device_type": "iPhone",

"device_model": "iPhone 11",

"os": "iOS",

"os_version": "14.6",

"lang": "es",

"location_status" : "always",

"session": 16,

"app_status": "foreground",

"app_version" : "1.2",

"moca_version": "3.6.0"

"dwell_time": null,

“user_properties” : {

key1: value2

hey2: value2

...

}

}]





    • Related Articles

    • How do I use the MOCA REST API?

      MOCA's REST API is a powerful tool to gather the data we have for your account, and process it at your end in order to get deeper insights into your data. The documentation for the REST API can be found here. It's extensive and covers all accessible ...

    • Example: Analytics data via REST API

      Our REST API is a powerful tool which allows you to gather data and process it depending on your needs. We have both the documentation and an API call tester embedded here. This example will show you how to get the actions and reached users per ...

    • How to set MOCA SDK to download only when connected to Wi-Fi

      The MOCA SDK has the capability to download data only when the "Wi-Fi Only" data transmission is activated. In order to do so, here are the calls for both Android and iOS: Android SDK MOCA API Java /** * Returns true if the "Wifi Only" data ...

    • Do you have a Web SDK?

      Yes, MOCA has the JS SDK that enables web applications written in HTML5/CSS to track a variety of user signals, such as browser, operating system, events triggered by user navigation and much more. MOCA JavaScript SDK is designed with this in mind: ...

    • How the MOCA SDK geo-location tracking works?

      Here's a diagram that draws the moving parts that involve location, and where our SDK comes into play: We rely strongly on the mobile device OS in order to gather precise and actionable locations.