Opt-in Forms

An opt-in form is a form you can add to your website, where your users can sign up for email or SMS messaging.

For more information, see the user guide: Opt-in Forms.

Installation

The Airship Web SDK provides plugins that extend its functionality to help with user acquisition and onboarding.

Use the load() method to load your plugin along with the plugin name and the url for the Airship-hosted CDN (Either North America or EU depending on your location), and any additional options.

UA.then(sdk => {
   sdk.plugins.load('my-plugin', 'https://my.plugin.url', {my_option: 'my_value'})
     .then(plugin => plugin.myMethod())
})

URL and options values are provided in the specific plugin sections.

See our Plugins class reference for more details.

URL, Options and Methods

When loading the plugin, you will provide the url for the CDN-hosted plugin along with an options object. URL values and available options and methods are described below.

URL

The URL will differ depending on whether you are using our North America or EU data center.

North America: https://aswpsdkus.com/notify/v1/ua-subscription-form.min.js
EU: https://aswpsdkeu.com/notify/v1/ua-subscription-form.min.js

Options

The following table covers the options that apply to all forms. See format- and platform-specific options below.

Key	Type	Required	Default	Description
`platform`	string	yes		Platform; one of `email` or `sms`.
`size`	string		`small`	Size; one of `large` or `small`.
`defaultTranslation`	string		`en`	Default language, must have a translation specified.
`i18n.{lang}.terms`	string	yes		Required for all translations.
`i18n.{lang}.heading`	string			Heading text on the form, omitted if not provided.
`i18n.{lang}.footer`	string			Footer text at bottom of form, omitted if not provided.
`i18n.{lang}.bannerUrl`	string			URL to a banner image, omitted if not provided.
`i18n.{lang}.placeholderEmail`	string			Placeholder email address displayed in the form.
`i18n.{lang}.placeholderMsisdn`	string			Placeholder MSISDN displayed in the form.
`i18n.{lang}.submitButton`	string			Submit button text.
`i18n.{lang}.invalidEmail`	string			Error message displayed when email is invalid.
`i18n.{lang}.invalidMsisdn`	string			Error message displayed when phone number is invalid.
`i18n.{lang}.genericError`	string			Error message displayed when registration fails.
`onRegister`	function			A function to be called when a registration is submitted.

The modal supports the options above, as well as additional optional timing options for automatic display. Any required options are only required if choosing to use the automatic display feature.

Key	Type	Required	Description
automatic.appearDelay	number	yes	Milliseconds to wait before displaying.
automatic.disappearDelay	number		Milliseconds to wait before closing if not interacted with.
automatic.askAgainDelay	number		Milliseconds to wait before asking again.
automatic.displayPredicate	function		A function that will be called before the modal is opened; should return a boolean indicating if it should be opened or not.

Email

When Email is selected as the platform, you may specify the following options:

Key	Type	Required	Description
`doubleOptIn`	boolean		When `true`, Double Opt-InA process where users who sign up for messaging must confirm opting in before they can receive messages. will be requested.
`getProperties`	function		An optional function that will be called to retrieve additional properties.

Double Opt In

When the doubleOptIn option is set true the following will occur:

Email addresses registered via the form will be opted into transactional messages, but not commercial
The registration will be sent such that Double Opt-InA process where users who sign up for messaging must confirm opting in before they can receive messages. is requested

You must have a double opt-in message configured within your project when using this feature. See: Email: Double Opt-In.

Properties

Additional properties may be sent along with the registration to distinguish the type of double opt-in message that should be sent. The getProperties option allows you to provide a function which will be called prior to registration, and may return a key/value object containing these properties. This function is asynchronous, and you may return a Promise which resolves to those properties.

Properties must be in the same format as required for custom events.

SMS

When SMS is selected as the platform, you must specify the following option:

Key	Type	Required	Description
`senderId`	string	yes	The Sender ID under which the customer MSISDN should be registered. Must be configured for your app.
`country`	string		Locks the form to a particular country, currently allowed are `US` and `CA` which have identical behavior.

Country

The country option sets the form into a configuration where it better matches expectations for a particular country, but only allows entries that match the selected country’s phone numbers.

When not set, a user must enter their full phone number, country code included.

US & Canada

When country is set to either US or CA (currently the only supported options), the form will do the following:

Prepend a 1 country code to the number, if one is not provided
Require an eleven-digit number (including the country code) to match the North American Numbering Plan

Localization (i18n)

The form supports internationalization options. Any text which is displayed on the form can be translated into your preferred language.

The form ships with English as the default unless you specify another language.

When the form is loaded, it determines the browser’s language and attempts to find that translation, falling back to the default if a translation for that language is not found. The options are the same for the email and SMS forms.

JavaScript

var options = {
  i18n: {
    // the ISO 639-1 two-letter language code; here `en` for English; you may
    // specify as many translations as you wish.
    en: {
      // required: terms which must be agreed to in order to sign up; be sure to
      // include a link to your terms and privacy policy.
      terms:
        'By opting into sms messages, I agree to the <a href="https://brand.example/terms">terms and conditions</a>.',
      footer:
         '<a href="https://brand.example/terms">Our Terms of Service are available here</a>.'

      // optional: a header which will be displayed at the top of the form
      heading: "Sign up for great deals!"
      // optional: a URL to an image to be displayed in the form
      bannerUrl: "https://brand.example/assets/banner.png"
      // optional: text which is displayed if an invalid email is entered
      invalidEmail: "That email is invalid, please try again."
      // optional: text which is displayed if an invalid phone number is entered
      invalidMsisdn: "That phone number is invalid, please try again."
      // optional: the text on the submit button within the form
      submitButton: "Sign Up"
    },
    // French
    fr: {
      // french translations, same keys as above...
    }
  },
  // optional: the default translation; `en` if not specified
  defaultTranslation: "fr"
  // remaining options...
}

Code examples

For both email and SMS modal forms the timing option is not required. Without the timing option, the modal will not display unless explicitly called to display.

Important

The suggested opt-in text and the design and usage guidelines provided in the Documentation are not intended to be legal advice. The suggested text should not be used “as is”, and is instead an example of what may meet opt-in standards or requirements. Please consult your legal counsel before implementing particular language for your campaigns to address your specific use case or regulatory requirements in your jurisdiction.

Email: Embedded

Embed an email form into an existing element on a page. This example specifies only the required options. See Options for more details.

HTML

<div rel="email-opt-in"></div>

JavaScript

var element = document.querySelector("[rel=email-opt-in]")
var options = {
  platform: "email",
  size: "large", // or "small" for a smaller form
  i18n: {
    en: {
      terms:
        'By checking this box, I agree that [COMPANY NAME] can be in touch with me by email to provide [insert purpose of communications - e.g. updates and marketing offers]. I understand that I can change my mind and opt out at any time by clicking the unsubscribe link in the footer of any email I receive from [COMPANY], or by contacting [email address]. I understand that I do not need to provide consent to these messages as a condition for any purchase. I understand that my information will be used as described here and in compliance with the <a href="https://brand.example/privacy">privacy policy</a>.',
      footer:
         '<a href="https://brand.example/terms">Our Terms of Service are available here</a>.'
    }
  }
}

UA.then(function (sdk) {
  return sdk.plugins.load("subscription-form", "https://aswpsdkus.com/notify/v1/ua-subscription-form.min.js")
}).then(function (formFactory) {
  formFactory.embedForm(element, options)
})

Display an email registration modal on an existing page, which will open automatically after a given amount of time.

JavaScript

var options = {
  platform: "email",
  size: "large", // or "small" for a smaller form
  i18n: {
    en: {
      terms:
        'By checking this box, I agree that [COMPANY NAME] can be in touch with me by email to provide [insert purpose of communications - e.g. updates and marketing offers]. I understand that I can change my mind and opt out at any time by clicking the unsubscribe link in the footer of any email I receive from [COMPANY], or by contacting [email address]. I understand that I do not need to provide consent to these messages as a condition for any purchase. I understand that my information will be used as described here and in compliance with the <a href="https://brand.example/privacy">privacy policy</a>.',
      footer:
         '<a href="https://brand.example/terms">Our Terms of Service are available here</a>.'
    }
  },
  automatic: {
      // required: how long until the modal appears. values are in milliseconds,
      // so multiply any value in seconds you wish to use by 1000
      appearDelay: 20 * 1000, // 20 seconds
      // optional: the modal will disappear after this amount of time if it is
      // not interacted with
      disappearDelay: 15 * 1000, // 15 seconds
      // optional: if the modal has been displayed before, don't show it again
      // for a period of time
      askAgainDelay: 7 * 24 * 60 * 60 * 1000 // 7 days
  }
}

UA.then(function (sdk) {
  return sdk.plugins.load("subscription-form", "https://aswpsdkus.com/notify/v1/ua-subscription-form.min.js")
}).then(function (formFactory) {
  formFactory.setupModalForm(options)
})

SMS: Embedded

Embed an SMS form into an existing element on a page. This specifies only the required options. See Options for more details.

HTML

<div rel="sms-opt-in"></div>

JavaScript

var element = document.querySelector("[rel=sms-opt-in]")
var options = {
  platform: "sms",
  senderId: "555555", // your sender id, required for SMS
  size: "large", // or "small" for a smaller form
  i18n: {
    en: {
      terms:
        'By checking this box, I consent to receive [marketing offers / abandoned cart reminders / order tracking / order information] text messages sent from [COMPANY NAME] at the phone number provided.  I verify that the phone number provided is my own. I understand that message and data rates may apply, and that I can text STOP to end all messages.  I understand that I do not need to provide consent to these text messages as a condition for any purchase. I understand that my information will be used as described here and in compliance with the <a href="https://brand.example/privacy">privacy policy</a>.',
      footer:
         'Messaging and data rates may apply. <a href="https://brand.example/terms">Our Terms of Service are available here</a>.'
    }
  }
}

UA.then(function (sdk) {
  return sdk.plugins.load("subscription-form", "https://aswpsdkus.com/notify/v1/ua-subscription-form.min.js")
}).then(function (formFactory) {
  formFactory.embedForm(element, options)
})

Display an SMS registration modal on an existing page, which will open automatically after a given amount of time.

JavaScript

var options = {
  platform: "sms",
  senderId: "55555",
  size: "large", // or "small" for a smaller form
  i18n: {
    en: {
      terms:
        'By checking this box, I consent to receive [marketing offers / abandoned cart reminders / order tracking / order information] text messages sent from [COMPANY NAME] at the phone number provided.  I verify that the phone number provided is my own. I understand that message and data rates may apply, and that I can text STOP to end all messages.  I understand that I do not need to provide consent to these text messages as a condition for any purchase. I understand that my information will be used as described here and in compliance with the <a href="https://brand.example/privacy">privacy policy</a>.',
      footer:
         'Messaging and data rates may apply. <a href="https://brand.example/terms">Our Terms of Service are available here</a>.'
    }
  },
  automatic: {
      // required: how long until the modal appears. values are in milliseconds,
      // so multiply any value in seconds you wish to use by 1000
      appearDelay: 20 * 1000, // 20 seconds
      // optional: the modal will disappear after this amount of time if it is
      // not interacted with
      disappearDelay: 15 * 1000, // 15 seconds
      // optional: if the modal has been displayed before, don't show it again
      // for a period of time
      askAgainDelay: 7 * 24 * 60 * 60 * 1000 // 7 days
  }
}

UA.then(function (sdk) {
  return sdk.plugins.load("subscription-form", "https://aswpsdkus.com/notify/v1/ua-subscription-form.min.js")
}).then(function (formFactory) {
  formFactory.setupModalForm(options)
})

Instead of using an auto-display modal, you may choose to control the modal’s display and closing yourself, using the open and close instance methods:

JavaScript

var options = {
  platform: "email",
  size: "large", // or "small" for a smaller form
  i18n: {
    en: {
      terms:
        'By opting into email, I agree to the <a href="https://brand.example/terms">terms and conditions</a>.'
    }
  }
}

UA.then(function (sdk) {
  return sdk.plugins.load("subscription-form", "https://aswpsdkus.com/notify/v1/ua-subscription-form.min.js")
}).then(function (formFactory) {
  var form = formFactory.setupModalForm(options)

  // attach a listener to some button element, and open the modal on click
  var button = document.querySelector("button[rel=open-modal]")
  button.addEventListener(function (ev) {
    ev.preventDefault()
    form.open()
  })
})

You may optionally pass a method to an auto-display modal that will be executed to determine if the modal should be allowed to open. If the function returns the value true, it will open. If it returns the value false, the modal will not open.

JavaScript

var options = {
  platform: "email",
  size: "large", // or "small" for a smaller form
  i18n: {
    en: {
      terms:
        'By opting into email, I agree to the <a href="https://brand.example/terms">terms and conditions</a>.'
    }
  },
  automatic: {
      appearDelay: 20 * 1000, // 20 seconds
      displayPredicate: function() {
        // your own code to determine if display is allowed
        return booleanValue
      }
  }
}

UA.then(function (sdk) {
  return sdk.plugins.load("subscription-form", "https://aswpsdkus.com/notify/v1/ua-subscription-form.min.js")
}).then(function (formFactory) {
  formFactory.setupModalForm(options)
})

Feedback

Was this page helpful?

Installation

URL, Options and Methods

URL

Options

Modal

Email

SMS

Localization (i18n)

Code examples

Email: Embedded

Email: Modal

SMS: Embedded

SMS: Modal

Controlling the modal

Modal Display Predicate