Data layer

Business & Enterprise · See plans

The Riddle data layer lets you pass external data into your Riddle – such as campaign IDs, user identifiers, or pre-filled form values. Use it to connect your Riddle data with your existing marketing or user data without asking your audience to re-enter information. Every value you pass is saved with the lead, exported as its own column in your leads download, and sent along with your tracking events.

Use cases:

  • Campaign IDs: add a parameter such as ?campaign_ID=newsletter-may to the links in your newsletter or ads. Every lead then shows which campaign it came from.
  • Logged-in user IDs: a Riddle behind a login passes your own user ID, so you can match leads to your CRM without collecting personal data a second time.
  • Pre-filled forms: pass the name and email address of a known user and the form in the Riddle is pre-filled; the user only confirms or corrects it.
  • Light or dark mode: switch the Riddle's palette to match your website's theme, see Change palette via data layer.

You can pass data using either UTM tags (simple, no coding required) or JavaScript (more flexible, real-time updates).

Set up data layer variables

  1. Edit your Riddle and go to PUBLISH.
  2. Click on Data layer.
    data layer tab in the publish section
  3. Click on ADD ITEM.
    set up data layer variable
  4. Enter an item key into the Key field.
    This is the name of the variable that you are sending to Riddle. If you are trying to catch a UTM tag with the name "id", then the item key needs to be "id". If your URL variable is mypage.html?source=xzy, then enter "source" as the key.
  5. Enter an item title into the Title field and click on ADD.
    The title helps you identify the data layer variable in your data exports and serves as the column header under which the values for the key are saved. If your UTM tag "id" has a value of "3434", you will see a column in your leads download with the item title in the column header and "3434" as the associated value.
    add a data layer item with key and title
  6. Save and publish your Riddle.

Use UTM URL variables

A UTM variable is a variable you add to the URL. The most common use cases for UTM variables are:

  • Identifying a marketing campaign
  • Identifying a user who clicked on a link from an email marketing campaign

A URL containing a UTM variable could look like this:

https://www.riddle.com/?campaign_ID=googleads

The UTM variable name is "campaign_ID", and the value is "googleads".

To add the campaign to the Riddle data from your audience taking your quiz, you can add a data layer variable with the key "campaign_ID" and a title of your choice. When Riddle saves the data from the quiz taker, the value for the campaign_ID will be saved along with all the other Riddle data.

As long as the data layer item key is exactly the same as the name of your URL variable, all data will be captured automatically. You don't need to do anything else other than test your setup at least once before running your campaign.

Use JavaScript

Using JavaScript is a more advanced technique to send data to the data layer. With JS you can pass any value to the Riddle in real time.

Let's say you placed your Riddle after a user login screen. In this case, you already have all the user info like name and email, and there would be no point in asking for this information again in a Riddle form. By passing a user ID to the Riddle data layer you can combine the Riddle data and your stored user data using the ID.

This means you don't need to transfer any personally identifiable information to Riddle. But of course, you could also send the user's name and email and use that to pre-fill a form, allowing the user to change that data if needed.

Push the key and value to the riddleDataLayer object.

This has to happen on the same page where you embedded the Riddle.

If you have data stored already and want to send it to the Riddle when the Riddle loads, add your script after the Riddle iframe is loaded and send the data to the Riddle data layer as follows:

window.riddleDataLayer = [];
window.riddleDataLayer.push({
    key: "mykey",
    value: "myvalue"
});

You can also update more than one variable with JavaScript using this notation:

<script>
window.riddleDataLayer = [
    { key: "source", value: "mysource" },
    { key: "medium", value: "mymedium" },
];
</script>

If you are using an iframe inside a Riddle and want to update the data layer while your audience clicks through the Riddle, you need to push data to the data layer from within the Riddle iframe. This requires minor manipulation of the sample code:

function storeText(){
            let input = document.getElementById("userInput").value;
        window.parent.postMessage({dataLayerItem: {key: 'userinput', value: (input)}}, '*')
        window.parent.postMessage({'ad-iframe-complete': true}, '*');       
        
    }

Identify your leads with your own ID

If your audience is already known to you, for example after a login, pass your own identifier as a data layer item instead of asking for personal data again. The ID is saved with the lead and appears as a column with the item title in your leads download, next to the lead ID Riddle generates for every person. Use it to match the lead to the record in your CRM or user database.

Data layer values are also sent along with every tracking event (the riddleDataLayer property, see JS events), so the same ID is available in Google Tag Manager, Google Analytics, Matomo or your custom tracking. You can switch this off per tracking tool in its Custom event configuration.

Answer the first block and change the palette via the data layer

In the data layer settings, you will also find two additional toggles. Both use a data layer value, but for a different purpose than saving data with the lead:

  • Submit first block via data layer – puts the first question of your Riddle into an email, newsletter or social post. Each answer is a unique link that casts the vote via the data layer and opens the full Riddle. See Embed in emails.
  • Change palette via data layer – switches the Riddle's palette from the page it is embedded on by passing the palette name or UUID as the r_p data layer item, for example to match your site's light or dark mode. See Change palette via data layer.

Both toggles can also be set for a whole project in the global publish settings.

Next steps

Table of Contents