🗒️ Contents:
In order to display in-app surveys to your users, you will need to add a Retently in-app script in your web application on all the pages where you want to survey your audience.
📝 NOTE: The in-app survey implementation requires technical skills and access to your web application's codebase. Feel free to forward this tutorial to your engineers as a reference for further implementation.
The in-app script
IMPORTANT: To ensure that your in-app survey will be correctly displayed in the mobile version of your web application, add the code below somewhere within your <head></head> tags.
<meta name="viewport" content="width=device-width, initial-scale=1.0">
The in-app script is located in each in-app campaign's editor mode, in the "Setup" section.
The script consists of two parts:
A
<div>element: Where the user's data will be populated.A
<script>element: The script responsible for generating the survey in the web application.
Here's an example with the full script:
<!--Add the <div> element between the <body> tag-->
<div
id="retently-survey-embed"
data-href="https://app.retently.com/api/remote/tracking/{{account_id}}"
data-rel="dialog"
data-campaign="regular"
data-email="{{variable}}"
data-firstname="{{variable}}"
data-lastname="{{variable}}"
data-company="{{variable}}"
data-tags="{{variable}}"
></div>
<!--Add the <script> element between the <body> tag, but after the <div> element-->
<script type='text/javascript'>
(function (d, s, id) {
var js, rjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s);
js.id = id;
js.src = "https://cdn.retently.com/public/components/embed/sdk.min.js";
rjs.parentNode.insertBefore(js, rjs);
}(document, 'script', 'retently-jssdk'));
</script>
Contact identification <div> element
This <div> element should be added between the <body></body> tags on a page (or multiple pages) in your web application.
In the <div> element you will pass the user's information that you need to import to Retently in the contact record that will be created for this particular user.
📌 IMPORTANT: User's information should be passed to the <div> via placeholders (variables) so that each user that will log into your web app and will reach the page with the in-app script installed will have their information sent to Retently via the script.
By default, the <div> element includes the following attributes:
data-email: This attribute is mandatory (you can't have contacts in Retently without email addresses).data-firstname: The value will be added as the user's first name in their contact record in Retently.data-lastname: The value will be added as the user's last name in their contact record.data-company: The value will be added as the user's company name in their contact record.data-tags: This attribute supports multiple values separated by commas (e.g.,data-tags="item1, item2"). Each value will be added a contact tag in the user's contact record.
You can also add additional attributes in the <div> element for other properties that you want to assign to the user's contact record in Retently.
In-app survey script
The <script> element should be added between the <body></body> tags on a page (or multiple pages) in your web application, and after the <div> element, to ensure that the user's information will be pushed to the <div> before the script runs.
The script is responsible for the following actions:
Send the user's information to Retently;
Check if the user matches any of your in-app campaigns;
Check if the user matches the schedule of the in-app campaign they should be surveyed in;
Render the survey on the page.
Understanding the in-app campaign script
The first part of the script, which is the <div> element, is used to collect the information about the user that has accessed a page in your web app where you have the in-app script installed.
The second part of the script does a little more.
Firstly, it runs automatically when a page is loaded (unless you handle it on your end) and upon execution, it will pull the user's data from the
<div>element and will import it as a new contact in your Retently account, along with any other properties and tags you're populating the<div>with. If you already have a contact in Retently with an identical email address (the matching is always made based on the email address), then the existing contact in Retently will be updated with the new values that you're passing to the properties in the<div>element.Afterward, the script will check all your active (switched ON) in-app campaigns' audience filters to assess whether the user matches any of your campaigns. If the user matches a campaign, then the script will proceed further and will check the campaign's schedule to check whether the user is eligible to see the survey on that specific day. If yes, then the survey will be rendered on the page; if not, then the user will not see anything.
And this cycle of checks will repeat every time a user will access a page in your web app where you have the Retently in-app script installed.
Survey contacts in multiple in-app campaigns
When surveying your audience in a single in-app campaign, everything is plain simple: You only need to add the script in your web application and your survey campaign will handle the rest.
But you can also run two or more campaigns at the same time, surveying different segments of your audience.
There are two options for how you can ensure that each one of your campaigns will survey a different segment of your audience.
Match users with a campaign's audience
By default, the in-app script will check your campaigns, one by one, in order to find the first one that will match your user based on the campaign's audience filters (which are configured by default to match all users) and the user's properties that you're passing via the <div> element, or already have assigned to the user's contact record in Retently.
📌 IMPORTANT: If your user matches the audience filters of multiple in-app campaigns, then they will be surveyed only in the first matching campaign that our system will find.
If you want to survey your users in different campaigns, then you will have to adjust each campaign's audience filters.
To explain with a real-life example: Let's say that you're passing the user's language (English or French) as a tag in the in-app <div> element.
Basically, user 1 will have the following attribute-value: data-tags:"English", and user 2 will have: data-tags:"French".
Using the values in these tags, you can survey each user in a different campaign. To achieve this, you will need to create two in-app campaigns, and in each campaign, in the "Audience" section, apply the following rules:
Campaign 1: Customer tag > is > English
Campaign 2: Customer tag > is > French
This way, users with the "English" tag will see the survey template assigned in Campaign 1, and users with "French" will see the survey template assigned to Campaign 2.
Of course, the use of tags is only an example, because you can use other user properties to distribute your audience between campaigns.
Add the campaign ID to the in-app script
However, if you don't want to deal with the audience matching logic, then there's a more straightforward solution.
You can instruct the script to survey the user in a specific survey campaign, and even if you have multiple campaigns running at the same time, and the user might match the audience of two or more campaigns, they will still see the survey in the campaign that you will specify in the <div> element.
To achieve this you will need to add a new attribute to the <div> element, specifically:
data-campaignID:"{{campaignID}}"
To get a campaign's ID, you will need to access the campaign's editor mode, and copy the campaign ID from the link in your browser:
Once you have copied the campaign ID, you can add it anywhere in the <div> element, here's a simplified example of the <div> element that includes the campaign ID:
<div
id="retently-survey-embed"
data-href="https://app.retently.com/api/remote/tracking/{{account_id}}"
data-rel="dialog"
data-campaignId="61fbc33c011b42998877321"
data-email="{{variable}}"
></div>
📝 NOTE: If you add the data-campaignID attribute in the <div> element, then you can delete the data-campaign="regular" from the element, as it will no longer be needed.
Contact properties management via in-app script
📌 IMPORTANT: Keep in mind that the in-app script always overwrites a contact's properties in Retently. If the user's contact record in Retently has a specific list of properties, and the <div> element of the script has a different set of properties and values, then the contact's data in Retently will be overwritten to match the information that you pass via the in-app script.
Aside from the main contact properties (email, first and last names, company name, and tags) that you can manage via the <div> element, you can also create and assign custom properties if needed. To get started, you will need to create the custom property in Retently first. Custom properties can be created on the Attributes page.
Retently supports the following four data types:
Text: The value will be stored as regular text.
Number: This property can store only numbers (this data type also supports numbers with decimals).
Collection: You can store an array of keywords (ex: "item 1, item 2, item 2"). However, since collection properties are highly similar to tags, we would suggest analyzing the tags approach instead of adding the complexity of the collections to your properties.
When creating a new property, make sure to choose its type correctly, to ensure that the values will pass the property type validation. For example, if you create a property "Signup date", and give it a "date" type, then this property will accept only date values, and anything else will be considered invalid and will be dismissed.
Identify a custom property's ID
By default, in Retently, properties are displayed in a user-friendly format, which supports capital letters and spaces. Basically, your property will look exactly as you have written it. We're calling this the property's label.
However, in our database, the property is saved in all lower-case and with underscores instead of spaces. This is the property ID.
In your in-app <div> element you will have to include the property IDs.
It's easy to figure out what is the ID of a property. All you have to do is to transform all the letters to lower-case and replace spaces with underscores.
Below I will list a few examples so that it's easier to understand how this works:
Label: Subscription (ID: subscription)
Label: Subscription Type (ID: subscription_type)
Label: This Is A Custom Prop (ID: this_is_a_custom_prop)
Adding custom properties in the script
Once you've created the property in your Retently account, you can add it to the <div> element.
Each custom property added should match this format: data-prop-{{property_id}}.
Let's say that you want to import your users along with their name, country, and a set of custom properties such as "User status", "Revenue", "Signup date".
Your <div> element would look like this:
<div
id="retently-survey-embed"
data-href="https://app.retently.com/api/remote/tracking/{{account_id}}"
data-rel="dialog"
data-email="{{variable}}"
data-firstname="{{variable}}"
data-lastname="{{variable}}"
data-prop-user_status="{{variable}}"
data-prop-revenue="{{variable}}"
data-prop-signup_date="{{variable}}"
></div>
Important takeaways on how the properties management works:
If you want to include a custom property in the
<div>element, make sure that you have it in Retently, otherwise, the property will be dismissed.If the user that was identified by the script already has a Retently contact record, and if the record already has one or more of the properties that you've included in the
<div>element, then the contact's properties will be updated with the new values that are sent by the script.Passing a blank value in the property via the
<div>element will remove that property from the user's contact record in Retently.Removing a property from the
<div>element will remove it from the contact record in Retently. If the contact has a set of properties that you haven't included in the<div>element, those will be removed from the contact's record. Please keep in mind that the in-app script will always overwrite the data that the user currently has in Retently.If one or more properties are missing from the contact, then there's a high chance that the property's value did not pass validation. For example, if the property is of a "date" format in Retently, make sure that you're sending the date value in the correct format.
CSP headers
If you're using Content-Security-Policy headers then you need to add the following CSP headers to allow the script to load and connect:
script-src
script-src 'https://cdn.retently.com/public/components/embed/sdk.min.js'
connect-src
connect-src 'https://app.retently.com'
Installing the script through Google Tag Manager