OptInOut

Documentation

Options

services

Optional but should be used, makes no sense otherwise Type: object - string keys with object as value Default: {}

The services you want to use to let users optIn/optOut to. Examples: Facebook Pixel, Google Analytics,... Each service is a string key with an object value which holds other service options, current used options are:

  • mode:
    • Required
    • Type: String
    • Allowed values: optIn, optOut
  • default:
    • Optional
    • Type: boolean
    • The default value for allowed

The string key is used for opting user in & out and for asking if it's allowed.

Example

OptInOut({
  services: {
    'facebook': {
      mode: 'optIn',
     }, 
     'analytics: {
       mode: 'optOut',
     },
  },
});

storages

Optional Type: object - string keys with storage objects as value Default:

 {
  cookie:  cookieStorage(),
  localStorage:  localStorage(),
  dataStorage:  dataStorage(),
}

The storages to save the optIn & optOut information. The order is important: It defines the priority/order in which the storages are asked for information when checking if something is allowed. For further information about the storage API and the default used storages see storages below.

plugins

Optional Type: array of plugin objects Default: []

Plugins which can listen for events triggered by this library or (possible in the future) can change how certain methods work. For further information see the plugins api below.

doNotTrack

Type: boolean Default: false

Defines if the browsers DoNotTrack option should be used. This will only be used if no optIn/optOut data is explicitly set (== as the default).

language

Defines any strings used/output by the plugin for i18n. Especially for the getStatus method. Currently the following strings are used by the core and included plugins/storages:

  • undefined
  • optedIn
  • optedOut
  • defaults (define a string used as the default status per service - object with serviceKeys as keys)

Included Storages

This library includes storage adapters for saving/getting data from cookies, the localStorage and a simple array.

Cookie Storage

Callable via:

  • Browser: OptInOut.storageAdapters.cookieStorage(options)
  • Module: src/storages/cookie

Options:

  • namespace:
    • Type: string
    • Default: optInOut
    • Defines the namespace used for cookies
  • expiration:
    • Type: Date
    • Default: Infinity
    • Expiration Date of cookies
  • domain:
    • Type: string
    • Default: false - does not set value
  • path:
    • Type: string
    • Default: false - does not set value
  • secure:
    • Type: bolean
    • Default: false
    • Whether HTTPS/SSL is used and the cookie should be set to secure

Local Storage

Callable via:

  • Browser: OptInOut.storageAdapters.localStorage(data)
  • Module: src/storages/localStorage

Options:

  • namespace:
    • Type: string
    • Default: optInOut
    • Defines the namespace used for localStorage

Data Storage

Callable via:

  • Browser: OptInOut.storageAdapters.dataStorage(data)
  • Module: src/storages/data

data is the array which is used to get values from and set values to. Should have a structure like the following:

  • serviceKey
    • optedIn: Date
    • optedOut: Date

Example Data:

{
  'facebook': {
    'optedIn': '2018-03-25',
  },
  'analytics': {
    'optedOut': new Date('2018-03-25'),
  },
}

AJAX-Data Storage

Extends the simple Data Storage with AJAX set methods. It is meant to store the data asynchronously on the server. The data should come from the server upon loading the page. Getting Data/a key via AJAX is not supported.

Callable via:

  • Browser: OptInOut.storageAdapters.ajaxDataStorage(data, options)
  • Module: src/storages/data-ajax

data is the array which is used to get values from and set values to. Should have a structure like the following:

  • serviceKey
    • optedIn: Date
    • optedOut: Date

options:

  • ajaxUrl:
    • Type: string
    • Default: false
    • The URL to be called by the AJAX function
  • ajaxFunction:
    • Type: function
    • Default: false
    • The AJAX (wrapper-)function. Gets passed the following arguments:
    • See below for example.
  • ajaxOptions:
    • Type: object
    • Default: {}
    • Additional options that should be passed to the ajax function (like HTTP method)
  • additionalData:
    • Type: any
    • Default: false
    • Additional data that should be passed to the ajax function (like authorization,...)

Example Function: Because of the arguments passed to the AJAX function it makes sense to wrap the real AJAX function (e.g. jQuerys .ajax function) in another function like so:

    function(ajaxUrl, ajaxData, ajaxOptions) {
        ajaxOptions.data = ajaxData;
        jQuery.ajax(ajaxUrl, ajaxOptions);
    }

Example Data:

{
  'facebook': {
    'optedIn': '2018-03-25',
  },
  'analytics': {
    'optedOut': new Date('2018-03-25'),
  },
}

Included Plugins

The library comes shipped with usefull plugins to handle opting in and out via buttons/links and using Google Tag Manager.

Link Helper

Handles clicks on links selected by the CSS selector - automatically calls optin/optout method. Usefull on privacy pages.

Callable via:

  • Browser: OptInOut.plugins.linkPlugin(options)
  • Module: src/plugins/link

Options:

  • optInClickSelector:
    • Type: string
    • Default: .optInOut-optIn
    • The CSS selector for the optIn button
  • optOutClickSelector:
    • Type: string
    • Defualt: .optInOut-optOut
    • The CSS selector for the optOut button

The DOM element can/must have the following data attributes:

  • service:
    • required
    • service to optin/optout
  • storage
    • optional
    • special storage in which this value should be set

Google Tag Manager

At the moment this plugin just sends the optIn and optOut events to GTM. For information how to get the optIn & optOut status via GTM and use it to enable tags see the GTM Tutorial below.

Callable via:

  • Browser: OptInOut.plugins.gtmPlugin(options)
  • Module: src/plugins/gtm

Options:

  • dataLayerKey:
    • Type: string
    • Default: dataLayer
    • The name of the dataLayer variable defined in the GTM configuration
  • eventNameSpace:
    • Type: string - false if should not be used
    • Default: false
    • This gets prepend to all events pushed to dataLayer (e.g.: namyNamespace.optIn instead of optIn)

Google Analytics OptOut

Sets the global ga-disable--property which disables Google Analytics tracking even if the code is loaded. See Google Analytics Documentation for more information.

Callable via:

  • Browser: OptInOut.plugins.analyticsPlugin(options)
  • Module: src/plugins/analytics

Options:

  • propertyId:
    • Type: string
    • Default: false
    • The property id of your Google Analytics property (UA-XXXX-1)
  • serviceKey:
    • Type: string
    • Default: analytics
    • The key of the OptInOut service which represents a Google Analytics service.

Reload

Callable via:

  • Browser: OptInOut.plugins.reloadPLugin()
  • Module: src/plugins/reload

Reloads the page after opting in or out. This is useful when you want to reload tracking scripts. You should therefore check if the user has opted in/out on the server. An alternative is to add the tracking scripts dynamically via javascript.

Storage Adapter API →