Skip to main content

Dotdigital v2 Integration

How to setup the Dotdigital v2 integration in Playable

Andreas Grosen avatar
Written by Andreas Grosen
Updated over 2 weeks ago

New feature in v2: Option to set the unique identifier as phone number.

  • Remember to include the country code in the phone number field on the registration form, as this is required in Dotdigital.

The Dotdigital v2 integration on the Playable platform allows customers to connect their Playable campaigns with their Dotdigital accounts. This integration enables transfer automation of user data and engagement metrics from Playable's gamification campaigns to Dotdigital, providing valuable insights and allowing further personalization and segmentation of marketing efforts within Dotdigital.

This guide walks you through:

  • Setting up the Dotdigital integration

  • How to use Triggers and Conditions

  • How to Mapping data fields

  • How to add Static Values

  • How to change data format

  • How to perform a Test

  • Troubleshooting

Prerequisites

Before you begin

Make sure you have access and have following ready:

  • API credentials from Dotdigital.

  • Administrator or a user with integrations access in Playable.

Setting up the integration

Add Integration

  1. Navigate to the Integrations tab.

  2. Click Add Integration > Select Email Provider > Click Dotdigital v2 > Click Configure now.

    • If you have set up an Dotdigital integration in a previous campaign, you will have an option to reuse that configuration.

  3. Paste the API key into the required field.

  4. Click Save to establish the connection.

📌 Note: Not all configurations is available in reuse, always check integration is set up correctly and perform a test - Find more about testing and troubleshooting.

Authentication

To connect with Dotdigital in Playable, you’ll need to authenticate with your API credentials:

  • API User

  • API Password

After a successful authentication, you can continue set Opt-in Type, ****trigger, conditions and mapping data fields. If any errors occur, check the troubleshoot section further down in the article.

💡 Tip: Ensure your have the right permissions in Dotdigital to create an API User. See how to setup an API User in Dotdigital.

Opt-in Type

You'll need to choose an opt-in type for your contacts. This determines how contacts are added to your mailing lists and the level of verification required.

Available opt-in types:

  • Unknown: Default type for bulk imports. Use with caution as there's no verification of consent.

  • Single: Basic opt-in where contact information is saved after form submission. Not recommended due to lack of verification.

  • Double: Requires confirmation email and consent record storage. You are responsible for sending confirmation and storing consent records.

  • Verified Double: Most secure option. Includes automatic confirmation email from Dotdigital to verify the contact's identity and consent.

💡 Tip: Using Verified Double opt-in might result in fewer total subscribers, but those who do confirm tend to be more engaged with your campaigns.

Subscription List

Choose an existing list from the dropdown menu or manually input the specific list ID where you want your contacts to be stored within your Dotdigital account. The list ID can be found in your Dotdigital dashboard.

Make sure to select a list that aligns with your campaign's audience segmentation strategy.

Triggers and Conditions

Triggers determine when data is sent to Dotdigital. You can configure triggers using either Form fields or Advanced options depending on your requirements.

Event Type

Choose between Form fields or Advanced as the event type.

  • Form fields:

    This option sends data based on specific form field submissions.

    • Example fields include:

      • Name

      • Email

      • Terms and Conditions (e.g., checkbox acceptance)

  • Advanced:

    This option allows for more complex trigger configurations using conditions:

    • Group:

      • All: Includes all participants.

      • Winners: Includes only participants who won.

      • Losers: Includes only participants who did not win.

    • Date Range: Specify a start and end date for when the trigger is active.

    • Time Range: Set a specific time range for when the trigger is active.

    • Metric Data: Use game metrics (e.g., game scores, correct answers, time used) as a condition to trigger integration.

    • Form Field(s): Define which specific form fields must be completed for the trigger to activate.

    • GET Parameters: Include URL-based GET parameters as part of the trigger condition.

Mapping Data Fields

Next step is mapping data fields between Playable and Dotdigital. This is to specify which data fields the data will be transfered to in Dotdigital.

Map Form Fields

Map the form fields submitted by users (e.g., name, email, terms acceptance) to the data fields in Dotdigital.

Dropdown List: If the ESP provides data fields that can be fetched dynamically, they will appear as selectable options in the dropdown menu for each form field.

Standard Campaign Fields to Map

  • Registration ID: Map this to a integer field - This capture the registration id for every registration.

  • Campaign Name: Map this to a string field - This capture the name of the campaign the integration is on.

  • Campaign ID: Map this to a integer field - This capture the campaign id.

  • Created On: Map this to a date field - This capture the date, when the user registered on the campaign.

  • Device: Map this to a string field - This field capture the type of device used (e.g., mobile, desktop).

  • IP Address: Map this to a string field for geo-targeting or security checks.

  • Created from URL: Map this to a string field - This field capture the URL where the registration was created.

  • Campaign URL: Map this to a string field - This field capture the campaign-specific URL.

Static Values

Static values allow you to send consistent, predefined data as part of the JSON payload, regardless of user input. These values can be mapped to fields and used for fixed parameters in your campaigns.

How to Set Up Static Values:

  1. Scroll to Integration setup > Static information.

  2. Add the value in the Static value field.

    • Example: Sending a constant source for all registrations.

      • Name: Source

      • Value: Playable

In this example, the field "source" always has the static value "Playable" in the payload.

Data formats and typecasting

  1. Scroll to the General Integration Settings section at the top of the integration settings page.

  2. Enable the Typecast Data Values checkbox to activate typecasting options.

  3. Once enabled, an Edit button will appear next to the data fields that support typecasting.

  4. Click the Edit button to configure the desired data format for the selected field.

    • Choose from predefined formats (e.g., string, integer, array).

  5. Save your changes to apply the new data format.

How to perform a test

  1. Remember to click Save after finishing setup in the integration.

  2. Go to Demo Url > now go through the campaign as one of your users would do, including registration form submitting and complete the game.

    • If trigger is set to “Prize won” or “Bulk prize won”, make sure a prize is available to be won. See tip below

  3. Verify the data is received in Dotdigital (e.g., check if the email was received).

  4. Resolve any errors with help in the troubleshooting section below.

💡 Tip: If you have the trigger set to “Prize won” or “Bulk prize win”, you can create a temporary prize to have a 100% win chance for you to perform testing.

Troubleshooting

If you encounter issues while integrating Dotdigital v2, here’s how to address common problems:

  • Authentication Errors: Ensure your project token, public key, private key, and API endpoint are correct. Verify that your Dotdigital API user has sufficient permissions. You can test the credentials in a tool like Postman to confirm connectivity.

  • Field Mapping Issues: Check that the mapped fields in Playable match Dotdigital’s field names exactly (case-sensitive). Use the Dotdigital dashboard to confirm data is being received correctly.

  • Data Transmission Errors: Review triggers and conditions to ensure they are configured properly. Use the Watchlog to check HTTP status codes:

    • 4xx: Verify authentication and request parameters.

    • 5xx: Contact Dotdigital support for server-side issues.

  • Testing Failures: Ensure the integration setup is complete, and all required fields are mapped. Perform a test and review the Watchlog for any errors. Adjust mappings or triggers as needed to resolve issues.

Locate the Watchlog

  • Go to Activity tab > go to Registrations sub-tab.

  • Locate the registration you want logs for > click on Watchlog button on the right of the registration.

    • If you can’t locate the Watchlog button, it means the Dotdigital v2 integration is paused or wasn’t triggered. Check trigger and conditions in the integration, and make sure the trigger and conditions are true.

Possible Error Messages

  • Issue: No lists were found

    Solution: Make sure Dotdigital API and Dotdigital account have read/write access to your list(s).

  • Issue: Authentication failure

    Solution: Double-check the authentication credentials. Verify the API key and account have correct permissions and scopes enabled.

  • Issue: No registration form found

    Solution: You have no registration form in your campaign. Why the Dotdigital v2 integration is unable to map form field data. Go to Build campaign > add a registration form at your preferred flow page.

📌 Note: Contact our support If issues persist, write what you did to get the error + error code + error description.

Resources

Internal links - Playable

External links - Dotdigital

Contact Support

For support assistance, contact Playable’s live chat support or email support@playable.com with questions or if any errors occur. Make sure to have checked our testing section and troubleshoot section above, to find solutions to the most errors.

Did this answer your question?