Quickstart

Install Entri in your application in just a few simple steps.

1. Add the Entri <script> tag

<script type="text/javascript" src="https://cdn.goentri.com/entri.js"></script>

Add this tag to your HTML. This creates a global entri variable on the page, so make sure the Entri tag is placed above any JavaScript that references it.

2. Fetch the JSON web token (JWT)

To launch the Entri modal window in a session, you'll need to fetch a JWT using the secret key and applicationId provided by the Entri dashboard. The JWT expires after 25 minutes. You can use any networking library you'd like. Here's an example using fetch:

fetch('https://api.goentri.com/token', {
  method: 'POST',
  body: JSON.stringify({
    // These values come from the Entri dashboard
    applicationId: "12345",
    secret: "12345-67890"
  }),
})
.then(response => response.json())
.then(data => {
  console.log('Success:', data); // { "auth_token": "exampletoken..." }
  // Save the token in a variable or state manager for later use
})
.catch((error) => {
  console.error('Error:', error);
});

3. Create the configuration object

Pass settings to the Entri modal window using a configuration object. Here's a basic example:

const config = {
  applicationId: "12345", // From the Entri dashboard
  token: mySavedToken, // The "auth_token" value saved in the previous step
  dnsRecords: [
    {
      type: "CNAME",
      host: "www",
      value: "m.test.com",
      ttl: 300,
    },
    {
      type: "TXT",
      host: "@",
      value: "sample-txt-record",
      ttl: 300,
    },
    {
      type: "MX",
      host: "host",
      value: "mailhost1.example.com",
      priority: 10,
      ttl: 300,
    },
  ],
};

🚧

Configuration Object Notes

• MX records require a priority
• When you add a new record to your configuration object, it takes some DNS providers 2-3 business days after the first time you call the entri.showEntri method with the new object to allow Entri to configure the record automatically on behalf of your customers. This is because certain DNS providers, such as Google Domains and Ionos, manually review the DNS Records you are setting up to ensure that they don't violate their policies. Until then, Entri will display manual setup instructions.

For complete documentation of the configuration object, see the API Reference.

4. Launch the Entri modal window

Call the showEntri method with your configuration object to trigger the Entri modal to appear.

<button type="button" onclick="entri.showEntri(config)">Launch Entri</button>

<button type="button" onClick={() => entri.showEntri(config)}>Launch Entri</button>

Note that this is a basic example, and you're free to structure your application code however you'd like.

5. Listen for the onEntriClose callback event

When a user closes the Entri pop-up modal, Entri sends a callback event that you can listen for. It includes information from the session such as the domain added, whether or not the user completed the setup, and the type of DNS set up for that user (automatic, manual or shared login).

function handleOnEntriClose(event) {
  console.log('onEntriClose', event.detail);
}
window.addEventListener('onEntriClose', handleOnEntriClose, false);

Here's an example of the returned event data:

{
  domain: "example.com", // Domain that the user entered. Can be null if the user exits before entering a domain.
  success: true, // Was the setup of the domain completed?
  setupType: "automatic" // Type of DNS setup. Can be "automatic", "manual", "sharedLogin" or null if the user didn't reach the set up stage.
}

When you receive the callback event you can display a success message in your application or move the user to a next step—whatever works best in your flow.

Advanced Usage

Here are a few examples of extra features to get even more out of your Entri installation.

Launch Entri with a prefilled domain

If you'd like to use a prefilled domain and bypass the domain input screen on the Entri modal, you can send a domain directly to Entri as part of the configuration object:

const config = {
  applicationId: "12345",
  token: mySavedToken,
  prefilledDomain: "example.com",
  dnsRecords: [...],
};

🚧

Syntax Notes

• prefilledDomain should not contain www. It should be a naked domain.
• At this time, Entri does not handle domain validation when you send a domain using the prefilledDomain variable. You'll need to handle validation in your application's UI.

Add a userId to track events via Entri webhooks

Entri uses webhooks to notify you when a user has added a domain and when the new DNS records have been propagated. In order to correlate the webhook event with the user that triggered it, add a userId to the configuration object. This should be the same ID that the backend of your application uses.

const config = {
  applicationId: "12345",
  token: mySavedToken,
  userId: "user12345",
  dnsRecords: [...],
};

Check if Entri supports automatic setup for a domain

You can check if a domain is eligible for automatic setup directly using the checkDomain method. This will tell you in advance whether the process fully automatic for your users or if they'll be asked to handle the DNS setup manually.

It takes two arguments:

• The domain (string) to be checked
• Your Entri configuration object (the same one used for launching the Entri modal window)

This is an asynchronous function, so you should consider handling the promise with then() or using the await operator—whatever works best in your application.

const domainCheckResult = await entri.checkDomain("http://mydomain.com", config);

console.log(domainCheckResult);

This will return an object, for example:

{
    "provider": "Google Domains",
    "setupType": "Automatic"
}

Dynamic configuration variables based on the user-inputted domain

You can insert dynamic variables into the dnsRecords section of your configuration object using {} syntax.

For example, if the user sets up blog.example.com, the following variables will be available:

• {DOMAIN} = example.com
• {SUBDOMAIN} = blog
• {SLD} = example
• {TLD} = com

You could then create the following configuration object:

const config = {
  applicationId: "12345",
  token: mySavedToken,
  dnsRecords: [
    {
      type: "CNAME",
      host: "{SUBDOMAIN}.xyz.example.com", // blog.xyz.example.com
      value: "custom-proxy.leadpages.net",
      ttl: 300,
    },
    {
      type: "TXT",
      host: "@",
      value: "{SLD}-{TLD}", // example-com
      ttl: 300,
    },
    {
      type: "MX",
      host: "host",
      value: "mailhost1.{DOMAIN}", // mailhost1.example.com
      priority: 10,
      ttl: 300,
    },
  ],
};

Email Provider SPF

DNS configurations support the variable {emailProviderSPF} for email provider SPF records. It outputs different values depending on the provider:

• If the provider is Google, it equals include:_spf.google.com
• If the provider is Microsoft, it equals include:spf.protection.outlook.com
• If the provider is unknown, it equals nothing (empty string)

For example, if you include this string in an SPF record and the customer-provided email provider is Google Workspace:

v=spf1 {emailProviderSPF} ~all

The value will be:

 v=spf1 include:_spf.google.com ~all

If Entri is unable to detect an email provider the value will be:

 v=spf1 ~all

For more information on SPF, see Handling DKIM, SPF, and DMARC Records.

Launch the Entri modal window with a CustomEvent

In addition to using the entri.showEntri() method, you can launch the Entri modal using a CustomEvent:

const showEntri = new CustomEvent('showEntri', {
  detail: {
    applicationId: "12345",
    token: "12345",
    dnsRecords: [...],
  },
});

document.dispatchEvent(showEntri);