So Annoying

Create annoying behaviors for sweet conversions. This library makes it easy to implement conditionally activated pop-ups, call-outs, etc.

Status

Installation

npm install --save so-annoying

Quick Guide

1. Import

Import the module.

import { annoy } from 'so-annoying'

2. Create an annoyance

annoy('newsletter-signup-2018-02', async () => {
  const email = window.prompt('Give us your email address.')

  // Perform some async action.
  await sendEmailToServer(email)

  // The return value is saved with the cookie. If the function doesn't return,
  // the cookie is not set.
  return email
})

3. That's it!

By default, your annoyance will be run once until the cookie expires (14 days by default).

Advanced Usage

options.shouldAnnoyIfCookiePresent

The shouldAnnoyIfCookiePresent option allows you to run the annoyance even if a cookie with the key is present. By default, this option always returns false (i.e. the annoyance should not be run if the cookie is present).

If you want to conditionally run the annoyance, provide a function that returns a boolean. The function receives the existing cookie value set from the previous occurance.

annoy(
  'newsletter-signup-2018-02',
  async existingEmail => {
    const message = existingEmail
      ? `Come back, ${existingEmail}!`
      : 'Give us your email address.'
    const email = window.prompt(message)

    await sendEmailToServer(email)

    return email
  },
  {
    shouldAnnoyIfCookiePresent: async email => await isUserSubscribed(email),
  },
)

Using the existing cookie value

The existing cookie value is provided as the only argument to annoyance.

// Example here...

The existing cookie value is also provided to the shouldAnnoyIfCookiePresent option. This allows you to conditionally run the annoyance even if the cookie is present.

// Example here...

Using Promise (or async/await)

The return value of the annoyance is used as the cookie value when it is set. If some type of async action needs to take place during the annoyance, you can utilize a Promise or async/await to control when the cookie is set.

// Example here...

API

annoy(key, annoyance, [options])

Run an annoying function if the user is new.

• key (string): Unique key to track the annoyance
• annoyance (function): Function to conditionally run. Return value is saved with the cookie. Existing cookie is passed to the function. If the function returns a Promise, the cookie will not be set until the Promise resolves.
• options (object): Includes all cookie options from RFC 6265
  • shouldAnnoyIfCookiePresent (function): Function to determine if the annoying function should be run even if the cookie is present. The cookie is passed as the first argument. If the function returns a Promise, the annoyance is not run until the Promise resolves.
  • path (string): Cookie path, use / as the path if you want your cookie to be accessible on all pages.
  • expires (Date): Absolute expiration date for the cookie.
  • maxAge (number): Relative max age of the cookie from when the client receives it in seconds.
  • domain (string): Domain for the cookie (sub.domain.com or .allsubdomains.com).
  • secure (boolean): Is only accessible through HTTPS?
  • httpOnly (boolean): Is only accessible by HTTP(S)?