GuidesAPI ReferenceSign-UpRecipes

In your CRM (Collect+)

Integrate your CRM with DataGuard

Suggest Edits
1772

🚧

Guidance Only

In this section we detail a possible method that can employed to integrate your system with DataGuard. You are able to choose any viable method to integrate using our open API, so you can pick and choose the elements that make most sense for you.

A Window into DataGuard

The simplest adoption within a CRM is to hold the permissions and preference data in DataGuard, and use capture points to show your staff users the current state and allow them to submit updates.

Most modern CRM systems can be configured to interact with external APIs, and allow custom JavaScript or iframes to be embedded. These elements allow you to to inject DataGuard functionality into your CRM.

If you want to go to a deeper level of integration you can add custom fields and metadata to extend standard CRM objects. You can then sync the DataGuard state back into these fields to hold a copy of the state in your system.

How to Integrate

Authenticate with our API

To use our open APIs to integrate with, you will need to hold authentication credentials within your CRM. These credentials need to be secure, and able to be called as needed.

Interactions with our API are done by using Auth0 JWTs (JSON web tokens). These typically have a 24hr time to live, so should be cached and re-used until expiry. A resilient pattern of refreshing these must be established in line with our fair usage policy.
NOTE - your API credentials are sent to you in your welcome emails. If you require, there is a pre-formed authentication call in our sample Postman collection.

Manage customer records

Hook into CRM events for your records to create and manage the corresponding record in DataGuard. You are able to do the following:

We recommend that you use your system ID to be stored as the DataGuard externalRef. This allows you to locate records within DataGuard simply as and when needed. It also allows you to generate access tokens that are required to show the existing state in the CRM capture point.

🚧

CRM IDs in DataGuard

Please note that some CRMs, including Dynamics, use the same string with either upper or lower case characters to locate the same record (e.g. AUT51-DFF and aut51-dff resolve to the same source record). DataGuard does not handle this in the same way, and would treat each as a separate record. To avoid unexpected behaviour, you may prefer to hold and use the DataGuard Citizen externalRef value in calls to our API.

Claim Default State

When you create a new customer record, you may want to claim a set of default permissions that are applicable to all. The customer would have seen your privacy policy and accepted the Terms & Conditions. It is not possible to claim consent by default as these, by nature, should be actively given by the customer. Only non-consent based options can be claimed as default.

Import Existing State

At the point of adopting DataGuard you will likely have a significant number of customer records as either contacts or leads within your CRM. These can be loaded in bulk using our import tool (see details here).

Embed the CRM Contact Point

There are a number of possible ways to integrate with your CRM and each will have its own nuances. There are two main paths to choose from. If your CRM allows you to host HTML and run JavaScript on some pages as if it were a normal website you may choose an implementation which operates in the same way as the standard Collect+ contact point.

Alternatively, if hosting a dynamic widget for each customer record is either not possible or simply too complex then we also offer a version of the contact point hosted by ourselves. This hosted version is designed to be deployed as the 'src' attribute for an iFrame element specified on your CRM page. The iframe allows you to set up quicker and is the simplest solution to adopt whereas hosting a contact point with your own config has the advantage in terms of customisation and styling options.

The example below shows the config version of the contact point and the corresponding 'src' attribute required for an iFrame deployment. 

<script>
  window.addEventListener('load', function() {
    StatefulWidget.load({
      id: '< ELEMENT ID >',
      templateId: '< STATIC TEMPLATE ID >',
      token: <DYNAMICALLY SUPPLIED TOKEN>
      ruleId: '< STATIC RULE ID >',
      displayName: '<DYNAMICALLY POPULATED DISPLAY NAME>',
      clientName: '<DYNAMICALLY POPULATED CLIENT NAME>',
    });
  });
</script>
<script src="https://scripts.consentric.io/capture-point.min.js"></script>

https://embed.consentric.io/capture-point?templateId=<TemplateId>&token=<TOKEN>&displayName=<DisplayName>&clientName=<ClientName>&ruleId=<RuleId>

Key Fields:

  1. In order for the audit history to store your organisational users' credentials against transactions they have captured, you pass in config values for displayName (mandatory), to represent the user and clientName, to represent the system (optional).

  2. You can set a ruleId to be applied that holds a list of possible channels that your users may receive permission updates from. This allows you to correctly reflect the route that the change was submitted via (e.g. post, phone, face to face, etc.). See the Rule Sets section for full details.
    If you do not configure a rule to display the channels, a default value of Web will be used in all transactions, which may not meet your requirements.

Sync State (optional advanced functionality)

You are able to receive real time updates from DataGuard using our subscription webhooks. You can take specific elements from the webhook payload to store for your customer records in custom objects, or by extending your CRM standard objects depending on what best suits your needs.

🚧

Multiple Capture Points

If multiple different capture points which render different sets of permissions and preferences are needed, then each requires its own templateId. A means for mapping which templateId is needed in each widget location (and possibly for which user and/or record type) will be required to provide the correct view.

Updated over 1 year ago