Integrations

Contents

Introduction

Radar supports a number of server-side integrations. Event integrations like webhooks, mParticle, and Braze allow you to send events from Radar to other systems. Geofence integrations like geofence sync and Yext allow you to sync geofences from other systems to Radar.

Event integrations

Event integrations allow you to send events from Radar to other systems.

Webhooks

You can use webhooks to send events and user state from Radar to your server, a Google or Firebase Cloud Function, an AWS Lambda Function, or any HTTP endpoint. From there, you can store events and user state in a database, send them to a marketing automation or analytics platform, and more.

Webhooks are a basic integration, available to Free and Enterprise customers.

Create a webhook on the Radar Integrations page under Webhooks. For Environment, choose Test to receive callbacks for events in the Test environment, or choose Live to receive callbacks for events in the Live environment. For Event Delivery, choose Single Event to receive a single event in each request, or choose Multiple Events to receive multiple events in each request when events occur simultaneously. Finally, enter a URL.

Whenever events are generated, Radar will send a POST request containing event and user data to the specified URL. You can also click the Test button to send test event and user data. If you chose Single Event, the request body will contain an event dictionary and a user dictionary. If you chose Multiple Events, the request body will contain an events array and a user dictionary.

To acknowledge receipt of the request, your webhook should return a 2xx status code (e.g., 200 OK, 201 Created, or 202 Accepted).

Sample request body
{
  "events": [
    {
      "_id": "56db1f4613012711002229f6",
      "createdAt": "2018-06-12T13:44:10.535Z",
      "live": true,
      "type": "user.entered_geofence",
      "user": {
        "_id": "56db1f4613012711002229f4",
        "userId": "1",
        "description": "Jerry Seinfeld",
        "metadata": {
          "session": "123"
        }
      },
      "geofence": {
        "_id": "56db1f4613012711002229fb",
        "tag": "neighborhood",
        "externalId": "4",
        "description": "Upper West Side"
      },
      "location": {
        "type": "Point",
        "coordinates": [
          -73.977797,
          40.783826
        ]
      },
      "locationAccuracy": 5,
      "confidence": 3
    },
    {
      "_id": "56db1f4613012711002229f7",
      "createdAt": "2018-06-12T13:44:10.535Z",
      "live": true,
      "type": "user.entered_place",
      "user": {
        "_id": "56db1f4613012711002229f4",
        "userId": "1",
        "deviceId": "7D5553E7-768A-4605-903B-D70637AC55F3",
        "description": "Jerry Seinfeld",
        "metadata": {
          "session": "123"
        }
      },
      "place": {
        "_id": "5a631784f61757fe9bb9847a",
        "name": "Starbucks",
        "chain": {
          "name": "Starbucks",
          "slug": "starbucks",
          "domain": "starbucks.com"
        },
        "location": {
          "type": "Point",
          "coordinates": [
            -73.977797,
            40.783826
          ]
        },
        "categories": [
          "food-beverage",
          "cafe",
          "coffee-shop"
        ]
      },
      "location": {
        "type": "Point",
        "coordinates": [
          -73.977797,
          40.783826
        ]
      },
      "locationAccuracy": 5,
      "confidence": 2
    }
  ],
  "user": {
    "_id": "56db1f4613012711002229f4",
    "live": true,
    "userId": "1",
    "deviceId": "7D5553E7-768A-4605-903B-D70637AC55F3",
    "description": "Jerry Seinfeld",
    "metadata": {
      "session": "123"
    },
    "updatedAt": "2018-06-12T13:44:10.535Z",
    "createdAt": "2018-06-10T11:23:58.741Z",
    "location": {
      "type": "Point",
      "coordinates": [
        -73.977797,
        40.783826
      ]
    },
    "locationAccuracy": 5,
    "stopped": true,
    "foreground": false,
    "deviceType": "iOS",
    "ip": "173.14.0.1",
    "geofences": [
      {
        "_id": "56db1f4613012711002229fb",
        "tag": "neighborhood",
        "externalId": "4",
        "description": "Upper West Side"
      }
    ],
    "place": {
      "_id": "5a631784f61757fe9bb9847a",
      "name": "Starbucks",
      "chain": {
        "name": "Starbucks",
        "slug": "starbucks",
        "domain": "starbucks.com"
      },
      "location": {
        "type": "Point",
        "coordinates": [
          -73.977797,
          40.783826
        ]
      },
      "categories": [
        "food-beverage",
        "cafe",
        "coffee-shop"
      ]
    },
    "insights": {
      "state": {
        "home": false,
        "office": false,
        "traveling": false
      }
    }
  }
}

Each webhook has a random security token. The authenticity of a request made to a webhook URL can be verified using the X-Radar-Signature header. If you chose Single Event, the header will contain an HMAC-SHA1 hash of the event ID using the security token as the key. If you chose Multiple Events, the header will contain an HMAC-SHA1 hash of the first event ID using the security token as the key.

Note that you can also receive events client-side via the SDK.

Segment

Radar can send events and user traits to Segment as a source. Segment can send those events and user traits to your warehouse and to hundreds of destinations.

Segment is a premium integration, available only to Enterprise customers.

In Segment, add Radar as a source and copy your write key. Then, on the Radar Integrations page under Segment Source, set Enabled to Yes and paste your write key. Note that you can set separate write keys for the Test and Live environments.

Whenever events are generated, Radar will call track and identify to send events and user traits to Segment.

By default, Radar userId maps to Segment userId for logged in users, and Radar deviceId maps to Segment anonymousId for logged out users. However, you can specify custom mappings by setting Radar metadata.segmentUserId or metadata.segmentAnonymousId. For example, on iOS:

// track logged out users with custom anonymousId mapping (not required if using default mapping)
Radar.setMetadata(["segmentAnonymousId": anonymousId])

// track logged in users with custom userId mapping (not required if using default mapping)
Radar.setMetadata(["segmentUserId": userId])

See the full list of event and user trait mappings in the Segment integration reference.

mParticle

Radar can send events and user attributes to mParticle as an input feed. You can use events and user attributes to build audiences in mParticle, and mParticle can send events and user attributes to hundreds of outputs.

The mParticle SDK can also install and initialize the Radar SDK as a kit.

mParticle is a premium integration, available only to Enterprise customers.

Feed

To configure the feed, in mParticle, add Radar input feeds for iOS and Android and copy your API keys and secrets. Then, on the Radar Integrations page under mParticle Feed, set Enabled to Yes and paste your API keys and secrets.

Whenever events are generated, Radar will send events and user attributes to mParticle. Events and user attributes from iOS devices will be sent to the iOS input feed, and events and user attributes from Android devices will be sent to the Android input feed. The Radar Test environment automatically maps to the Development environment in mParticle, and the Radar Live environment automatically maps to the Production environment in mParticle.

See the full list of event and user attribute mappings in the mParticle integration reference.

Kit

To configure the kit, on the Radar Settings page under Keys, copy your test and live publishable keys. Then, in mParticle, add and enable Radar outputs for iOS and Android, paste your keys, and choose whether to run automatically.

Install the kit using CocoaPods or Carthage on iOS and Gradle on Android. See the iOS kit code and readme, Android kit code and readme, and mParticle Kit documentation for Radar.

The kit will initialize the Radar SDK and identify the user with the mParticle customer ID. In addition, if you chose to run automatically and the user has granted permissions, the kit will automatically track the user's location in the foreground on app open and/or in the background.

Braze

Radar can send events and user attributes to Braze (formerly Appboy).

Braze is a premium integration, available only to Enterprise customers.

On the Braze Developer Console page under Rest API Keys, create and copy a new app group API key with users.track permissions. Under Identification, copy your iOS and Android app identifiers. Then, on the Radar Integrations page under Braze, set Enabled to Yes and paste your API key and app identifiers. Note that you can set separate API keys and app identifiers for the Test and Live environments. Finally, if your account is not on https://rest.iad-01.braze.com, select the appropriate API Endpoint.

Whenever events are generated, Radar will send custom events and user attributes to Braze. Events and user attributes from iOS devices will be sent using your iOS app identifiers, and events and user attributes from Android devices will be sent using your Android app identifiers.

By default, Radar userId maps to Braze external_id for logged in users. However, you can track logged out users or specify custom mappings by setting Radar metadata.brazeAlias or metadata.brazeExternalId. If you set metadata.brazeAlias, you must also add a matching alias in Braze with label radarAlias. For example, on iOS:

// track logged out users with alias (deviceId recommended, not required if not tracking logged out users)
Radar.setMetadata(["brazeAlias": deviceId])
Appboy.sharedInstance()?.user.addAlias(deviceId, withLabel: "radarAlias")

// track logged in users with custom external_id mapping (not required if using default mapping)
Radar.setMetadata(["brazeExternalId": userId])
Appboy.sharedInstance()?.changeUser(userId)

See the full list of event and user attribute mappings in the Braze integration reference.

Urban Airship

Radar can send events to Urban Airship.

Urban Airship is a premium integration, available only to Enterprise customers.

On the Urban Airship APIs & Integrations page, create a custom event token and copy the app key and access token. Then, on the Radar Integrations page under Urban Airship, set Enabled to Yes and paste your app key and access token. Note that you can set separate API keys for the Test and Live environments.

Whenever events are generated, Radar will send custom events and user attributes to Urban Airship.

See the full list of event and user attribute mappings in the Urban Airship integration reference.

Mixpanel

Radar can send events and user properties to Mixpanel.

Mixpanel is a premium integration, available only to Enterprise customers.

On the Mixpanel Project Settings page, copy the token from the Management tab. Then, on the Radar Integrations page under Mixpanel, set Enabled to Yes and paste your token. Note that you can set separate tokens for the Test and Live environments.

Whenever events are generated, Radar will send custom events and user properties to Mixpanel.

See the full list of event and user property mappings in the Mixpanel integration reference.

Leanplum

Radar can send events and user attributes to Leanplum.

Leanplum is a premium integration, available only to Enterprise customers.

On the Leanplum App Settings page, click Keys & Settings and copy the App ID, Production Key, and Development Key. Then, on the Radar Integrations page under Leanplum, set Enabled to Yes and paste the app ID and API keys. The Radar Test environment automatically maps to the Development environment in Leanplum, and the Radar Live environment automatically maps to the Production environment in Leanplum.

Whenever events are generated, Radar will call track and setUserAttributes to send events and user attributes to Leanplum.

See the full list of event and user attribute mappings in the Leanplum integration reference.

Iterable

Radar can send events and user data to Iterable.

On the Iterable API keys page, create and copy a Mobile API key. Then, on the Radar Integrations page under Iterable, set Enabled to Yes and paste your key. Note that you can set separate keys for the Test and Live environments.

Whenever events are generated, Radar will send custom events and user data to Iterable.

See the full list of event and user property mappings in the Iterable integration reference.

Amplitude

Radar can send events and user properties to Amplitude.

This integration is in closed beta. Interested? Contact us.

Geofence integrations

Geofence integrations allow you to sync geofences from other systems to Radar.

Geofence sync

Radar can automatically sync geofences nightly from CSVs.

Geofence sync is a premium integration, available only to Enterprise customers.

On the Radar Integrations page under Geofence Sync, set Enabled to Yes. Enter a Notification Email to receive success and failure confirmation emails. Then, choose a Protocol:

  • Choose HTTP for geofence CSVs at public HTTP or HTTPS URLs. Enter the URLs of the geofence CSVs.
  • Or, choose AWS S3 for geofence CSVs in a private S3 bucket. Enter an S3 bucket region, S3 bucket name, and the S3 object keys of the geofence CSVs. Finally, enter the AWS access key ID and secret access key of an IAM user with GetObject permissions for the specified S3 bucket and objects.

Note that you can set separate CSVs for the Test and Live environments.

The geofence sync CSV format is the same as the geofence import CSV format.

When you click Save and Sync, Radar will attempt a one-time sync and send an email on success or failure. Radar will then attempt syncs nightly.

Brandify

Radar can sync locations from Brandify as geofences in Radar, powered by geofence sync.

Brandify is a premium integration, available only to Enterprise customers.

Ask your Brandify account manager to enable a published CSV of your locations and associated metadata. Then, on the Radar Integrations page under Geofence Sync, set Enabled to Yes. Enter the published CSV URL. Note that you can set separate URLs for the Test and Live environments.

The geofence sync CSV format is the same as the geofence import CSV format.

When you click Save and Sync, Radar will attempt a one-time sync and send an email on success or failure. Radar will then attempt syncs nightly.

Yext

Radar can sync locations from Yext as geofences in Radar.

Yext is a premium integration, available only to Enterprise customers.

On the Radar Integrations page under Yext, click Connect. You will be redirected to Yext, where you can authorize Radar. If authorization succeeds, you will be redirected to the Radar Geofences page. If authorization fails, you will be redirected back to the Radar Integrations page.

Radar will automatically sync all locations from Yext as geofences in Radar, and keep geofences in sync when you create or update locations in Yext. By default, Radar will map Yext location name to geofence description, set location as geofence tag, map Yext store ID to geofence externalId, map other Yext metadata to geofence metadata, set radius to 100 meters, and set enabled to false if the location is closed in Yext. Radar will sync geofences both to the Test and Live environments.

To change any of these defaults, please contact support.

Support

Have questions after reading the documentation? We're here to help! Click the button on the bottom right of any page to chat with us, or email us at [email protected].