Nudge API

In addition to the nudge editor in our platform, nudges also comes with a powerful API that let's you create, control and make use of various events. The nudge API can also be used in addition to nudges created with the platform, to easier maintain the text fields used.

Nudge types

There's various types of nudges to make use of, based on your needs. Each type comes with its own properties and functionality, but all share a set of the same values. Values needs to be wrapped in a sections array, to split up object throughout the nudge as well. See each nudge type below for example recipes.

Nudges created with the editor each have a identifying slug string, which is used when calling the nudge from the API.

Form nudge

A form nudge is a great way to handle subscriptions on your website without being too intrusive, for example a newsletter signup, or to download an e-book. It comes with a call to action in form of an input and a button. When the form is submitted it can call a webhook, and trigger a specific dialogue of your choice.

Example recipe

{
	"dialogueId": "a6e66595-88e1-46d7-9dbb-947ad87a5973",
	"webhook": "https://example.com/signup",
	"sections": [
		{
			"title": "Want to stay up to date?",
			"description": "Sign up for our newsletter and never miss our best offers!"
		},
		{
			"form": {
				"input": {
					"label": "Email",
					"type": "email",
					"placeholder": "test@example.com",
					"required": true
				},
				"button": {
					"title": "Sign up"
				}
			}
		}
	]
}

Product nudge

With the product nudge you can showcase a hand picked selection of products, and is great for promoting either current offers or best sellers. Similar to the form nudge it also comes with a call to action, but in the form of a button. Each product is represented with a image, title, description, price and call to action. In the example below, we use multiple sections to divide up our nudge content.

Example recipe

{
	"sections": [
		{
			"title": "Our best sale continues!",
			"description": "50% on our most popular shoes.",
			"buttons": [
				{
					"label": "View all",
					"value": "http://example.com/sale"
				}
			]
		},
		{
			"products": {
				"title": "The most popular products:",
				"items": [
					{
						"title": "Adidas",
						"description": "Stan Smith - white",
						"image": "http://lorempixel.com/200/200/shoes/",
						"price": "699,-",
						"productUrl": "http://example.com/stan-smith",
						"linkUrl": "http://example.com/sale",
						"linkText": "View all on sale"
					}
				]
			}
		}
	]
}

Multiple choice

Multiple choice nudge is a great way to collect feedback on various aspect of your website. It supports an array of buttons, which each has an attached dialogue it will trigger when pressed. In the example below, we use multiple sections to divide up our nudge content.

Example recipe

{
	"sections": [
		{
			"title": "Product feedback",
			"description": "You seemed interested in our product! We would love to know you didn't want to try it."
		},
		{
			"choices": {
				"buttons": [
					{
						"text": "I love it",
						"triggerDialogue": "a4bfc101-3a07-4c16-955d-9aa9575666c6"
					},
					{
						"text": "I hate it",
						"triggerDialogue": "a4bfc101-3a07-4c16-955d-9aa9575666c6"
					},
					{
						"text": "I didn't understand",
						"triggerDialogue": "a4bfc101-3a07-4c16-955d-9aa9575666c6"
					},
					{
						"text": "Other",
						"triggerDialogue": "a4bfc101-3a07-4c16-955d-9aa9575666c6"
					}
				]
			}
		}
	]
}

Combining nudge from editor and API

When using the API to trigger a nudge, it's possible to pass both a nudgeLayout object, and a slug string. When this is done, both nudges will be combined into one. This can be useful if you have nudge created using the API, but need to easily maintain texts from the platform.

Custom nudge

The custom nudge is a more powerful nudge type, which let's you completely customize the contents of the nudge. It accepts either a string or a function, which can contain some HTML code.

Custom nudges supports its own trigger function, depending on whether or not you want our template to wrapp your nudge or build your own.

HTML as string

If you want the nudge to be completely custom, it's fine to send in the HTML as a string. See example below.

const html = `
  <style>
    .nudge-text {
      width: 50%;
    }

    p {
      color: #333;
      font-size: 14px;
    }
  </style>
  <div class="nudge-wrapper">
    <div class="nudge-text">
      <p>Here you can display whatever contents you want.</p>
      <p>Styling is also supported, and will be renderrerd!</p>
    </div>
  </div>
  <script>
      console.log("Even script tags are supported!");
  </script>
`;

HTML as function

HTML can be passed as a function to make use of text content from the platform. This is useful if you have a custom nudge solution, but need to easily maintain its texts. Simply create a custom nudge from the editor, and call the text blocks slug to display it.

const html = (textContent) => `
  <style>
    .nudge-text {
      width: 50%;
    }

    p {
      color: #333;
      font-size: 14px;
    }
  </style>
  <div class="nudge-wrapper">
    <div class="nudge-text">
      <p>${textContent.slug}</p>
      <p>${textContent.anotherSlug}</p>
    </div>
  </div>
`;

Triggering a custom nudge

Triggering a custom nudge is slightly different than the other nudge types, as it uses HTML content. You can choose between using our nudge template, or create your own from scratch. The template includes our nudge element with built-in styling and responsiveness.

Using our nudge template, the content sent as it can be triggering like this:

const html = `
  <div>
    <p>HTML contents</p>
  </div>
`;

const nudgeLayout = {
	sections: [
		{
			html,
		},
	],
};

window.kindlyChat.showNudge({ nudgeLayout });

On the other hand, a completely custom solution use the following function:

const html = `
  <div>
    <p>HTML contents</p>
  </div>
`;

const content = {
	html,
	onRendered: (element) => (element.style.height = "3000px"),
};

window.kindlyChat.showCustomNudge({ content });

Functions and callbacks

For a comprehensive list of functions and callbacks can be found here