Apps

You can have any number of apps for your organisation. Typically these will have been created for you as part of your integration. Each app has an ID.

Each app can have individual native Android, iOS and Web apps, which will have the same app ID but will be assigned separate API keys with which to communicate with the Xray platform.

The app edit screen

From the app edit screen you can enable or disable different app flavours as well as retrieve your unique app ID and API keys.

For your Android and iOS apps you will need to provide push credentials before you can start messaging your users. In most cases this will be done for you as part of your integration but you may need to update the certificates and keys at some point, in which case edit the settings for the Apple Push Notification Service (APNs) and Firebase Cloud Messaging (FCM) for your iOS and Android apps respectively.

For Web apps we generate the appropriate keys for you - these will need to be used when your developers integrate our Web SDK. You can add a default icon that will be used in web push messages when no specific icon has been set. This should be a .PNG and around 256x256 pixels. You can use colour images but bear in mind that on some platforms the operating system will override this and use a colour that matches the surrounding UX.

Enable messaging

Before we can send push messages to your app users, you need to provide us with APNs certificate and FCM server key for authorisation. This should generally already be configured for you, but you may need to check or refresh certificates at some point.

  • Navigate to the Apps section in your 360dialog dashboard.
  • Hover over your app in the list and click the edit icon. (You may alternatively click on the apps dropdown menu in the top left corner of the dashboard and select “App settings” directly)

App switch with link to the app settings

  • In the APNs section of the iOS app settings, click “Enable”.
  • Select your authentication method. This will be either Certificate or a Provider Authentication Token

APNs certificate

Upload APNs certificate

  • Upload the certificate by drag and drop or browsing your local machine.
  • Provide the password if the certificate file is password protected.
  • Hit “Save certificate”.

APNs Provider Authentication Token

Upload APNs token

  • Upload the file containing the authentication token (the file should contain only one token)
  • Add your Key and Team IDs as well as your app’s bundle id, remember that tokens can be used for multiple apps so make sure the correct information is given here
  • Select the correct environment, normally only debug and developer versions of an app will use the APNs sandbox environment, for most apps the correct environment will be production
  • Save your token

FCM tokens

Add FCM token

  • Add your FCM authorisation token in the designated field, we strongly recommend only using the newer, longer keys provided by FCM, never upload an older GCM key as these, as well as the shorter form FCM keys are gradually being phased out and are not guaranteed to work stably

please note

For security reasons, once your push credentials have been uploaded they will not be visible. If having problems during integration you can ask your integration manager to confirm that the correct details are in our system but these will never be disclosed via the public API.

Where to find your APNS certificate or token

You have to request and download your APNS certificate from Certificates, Identifiers & Profiles section in your Apple developer account.

Where to find your FCM server key

The FCM server key is available in the Cloud Messaging tab of your Firebase console settings pane.

Frequency capping

Frequency capping rules are applied per app but you can specify different rules per message type.

A frequency capping rule consists of a message type, a maximum allowed value and a time frame, and this works on a per-device basis. For instance, with a frequency cap of 3 push messages per device, different users may get a different three messages but not more.

Multi-step campaigns

If you have a multi-step campaign and a user does not receive a message from the series due to frequency caps it will be dropped and, unless frequency apps are again reached, they will receive the next message in the workflow. For priority multi-step campaigns you can use the ignore frequency caps setting to ensure that a user will receive all messages in a series.

Global Control Group

If you have enabled a Global Control Group for your app you will see the current percentage distribution here.

A Global Control Group can help you measure the impact of your campaigns over the entire user base by creating a segment of users who will never receive messaging. It is best to set up your Global Control Group during the launch phase as changing the size later on is ill-advised.

Talk to your integrations or account manager about whether a Global Control Group would make sense for you app, you can read more about the feature in our blog post.

Custom personalisation parameters

You can personalise messages with standard device or user fields, as well as create your own personalisation parameters which can be set using a standard or custom event, either from our SDK or a custom event or data stream you might have set up for your app.

You’ll see a list of currently available personalisation attributes at the top of the page and can add more by scrolling down to the + button.

add custom attributes for targeting and personalisation

You can pick any of our standard events or custom events tracked in your app to update this attribute and which event property gives us the new value.

Depending on the size of your userbase it may take a while to prefill all personalisation attributes. We greatly recommend settling on a strategy early on in the integration of your app and pre-configuring your attributes so that you can get up and running with 1-on-1 personalised messages in your first campaigns.

We will always update the attribute to the latest state based on your events, even if it is updated with an empty value, in which case it will be not present for this user.

You can use more than one event and more than one event property to update a custom personalisation attribute. In the example above you can see both the checkout event and the purchase event being used to update the last basket size. In this example, if a user adds 5 items to the basket at checkout then adds another recommended item during purchase, following the purchase this custom personalisation attribute would have the value of 6. Should the user shop again and add 2 items to the basket, the custom personalisation attribute will be overwritten with this value.

For standard attributes such as device level information and ‘environment’ information - which includes things like app version or app id - you do not need to set anything up, we will keep these up to date.

For more on how to use personalisation in your messages, see the workflows chapter.

Naming personalisation attributes

You can give any name you like to an attribute as long as it does not contain any full stops (‘.’), spaces (’ ‘) or special characters such as @#$% or &?^!. When you add these they will be prepended with custom.

Email

Through our partner SendGrid you can trigger email templates to go out to your users’ email inboxes based on the same event-based triggers and complex targeting as you can for any campaign, you can even include email as part of a multi-step, multi-channel workflow.

You will need to sign up for an account at SendGrid, if you haven’t heard of them already they have fast risen to become one of the leading companies in the email space, especially beloved by tech-first companies; boasting Uber, AirBnB and Spotify among the customers who trust them and their deliverability rates.

Once you have signed up you will need to generate an API key. We need at least full Mail Send rights to trigger templates and, if you will be using our UI, we recommend also granting the API key read rights for the Template Engine so that we can preview templates as well as load all necessary keys needed for personalisation of a given template. It is important to remember that this key will only be shown once so copy it down somewhere safe, preferably to an encrypted key store protected with a strong password.

Generate an API key for sending mail and managing templates

Enter the API key you generated and the default sender address and name you would like to appear for each email. These can be overriden both on the campaign level in our own system as well as in the SendGrid dashboard. You can read more about that in the Workflows section.

To track all events you will also need to set up an Event Notification stream from SendGrid to us. You can do this in the Mail Settings page by opening the Event Notification tab. If you haven’t already received credentials from our integrations team, now is the time to ask for an event-scoped username and password which we will use to authenticate the SendGrid event stream. Create your webhook URL following the example below and paste it into the HTTP POST URL field.

https://USERNAME:PASSWORD@rt.360dialog.io/xray/events/etl/json/v1/events/sendgrid

Enable all events by checking the check boxes and save your configuration. You can test the integration using the button provided, although as the event won’t appear in our reporting database for you to check yourself, you will have to ask one of our integrations team to confirm that the event has arrived.

That’s it.