@wiryio/wirypop v1.0.3

WiryPop!

Open source, lightweight, developer-friendly, and customizable website popups. Built with Svelte.

Playground and configuration tool: https://wiry-io.github.io/wirypop

Features

• Customizable and mobile-friendly
• Privacy-friendly, without cookies
• Without any external dependencies or services
• Supports triggers - enter, exit intent, scroll, click
• Supports in-browser targeting by language, OS, geolocation, and more
• Data submission to your API
• Use custom Svelte components

Get started

The easiest way to get started with WiryPop! is with the hosted builds. Simply include the script into your website and configure your popups:

1. Using <script>

Use this URL or download dist/wirypop.js:

https://cdn.jsdelivr.net/npm/@wiryio/wirypop@1.0.3/dist/wirypop.js

Example usage:

<!-- Load WiryPop script -->
<script async src="https://cdn.jsdelivr.net/npm/@wiryio/wirypop@1.0.3/dist/wirypop.js"></script>

<!-- Somewhere in your app -->
<script>
  // attach the 'ready' listener which fires once the script is loaded
  document.body.addEventListener('wirypop', () => {
    // create instance
    const wirypop = new WiryPop();

    // configure your popups
    wirypop.popups([{
      animation: 'bouncein',
      closable: true,
      content: 'This will be shown <b>inside</b> the popup!',
      size: 'small',
      position: 'bottom-right',
      trigger: 'exit'
    }]);
  });
</script>

2. Using npm module

npm install @wiryio/wirypop

import WiryPop from '@wiryio/wirypop';

const wirypop = new WiryPop();

Tip: use our playground and configuration tool https://wiry-io.github.io/wirypop to build and preview your popups

WiryPop options

The configuration options can be passed into the constructor or as HTML attributes on the script tag.

interface IPopOptions {
  // The base url used for relative paths. Defaults to `location.origin`.
  baseUrl?: string;

  // Set the environment to the 'development' mode. Defaults to false.
  dev?: boolean;

  // How to handle Do Not Track settings. 'auto' detected DNT using `navigator.doNotTrack`. Defaults to 'auto'.
  doNotTrack?: boolean | 'auto';

  // Sets the environment to the 'live' mode (production). Only 'live' popups will be shown. Defaults to false.
  live?: boolean;

  // Optional target element where to attach popups. Default to `body`.
  targetEl?: HTMLElement;
}

Configuration options in the scritp tag:

<script
  async
  src="https://.../wirypop.js"
  data-live="true"
  data-do-not-track="auto"
></script>

Popup configuration

Popups are configured as simple JSON objects and configured using wirypop.popups(popups: IPopupOptions[]):

interface IPopupOptions {
  // Popup animation
  animation?: 'bouncein' | 'fadein' | 'zoomin' | 'slideup' | 'slidedown' | 'slideleft' | 'slideright';

  // Whether to show the page backdrop (dark page overlay). Defaults to false.
  backdrop?: boolean;

  // Whether to show a closing button. Defaults to true.
  closable?: boolean;

  // Optional component config, applies only to custom Svelte components
  config?: IParams;

  // Popup content. Can be a HTML string, a CSS selector, or a url of a custom Svelte component
  content: string | unknown;

  // Show popup after a delay
  delay?: number;

  // Apply `position: fixed`. Defaults to true.
  fixed?: boolean;

  // Whether to show in fullscreen (cover the whole page). Defaults to false.
  fullscreen?: boolean;

  // Whether to automatically show in fullscreen on small viewports (<= 600px) regardless of the `size`. Defaults to false.
  fullscreenOnSmallViewport?: boolean;

  // Optional popup ID. Used to identify the popup.
  id?: string;

  // Whether the popups 'live'. Defaults to false.
  live?: boolean;

  // Whether the popup can be closed by clicking on the backdrop. Defaults to false.
  persistent?: boolean;

  // The position of the popup on the screen. Default to 'center'.
  position?: 'center' | 'bottom-left' | 'bottom-right' | 'top-bar' | 'bottom-bar' | 'sidebar-left' | 'sidebar-right';

  // Whether to lock the scroll position of the page while the popup is open. Defaults to false.
  preventScroll?: boolean;

  // Optional custom reference. Used for submissions to identify the popup or the purpose of the popup.
  reference?: string;

  // The size of the popup. Default to 'auto'.
  size?: 'auto' | 'small' | 'medium' | 'large';

  // Custom strings (transalations). Applies only to custom Svelte components
  strings?: { [key: string]: string };

  // Optional submission URL.
  submitUrl?: string;
  
  // A chain of targeting conditions.
  targeting?: IPopupTargetingCondition[];

  // Optional component theme. Applies only to custom Svelte components.
  theme?: string;

  // The trigger events which opens the popup.
  trigger?: 'enter' | 'exit' | 'click' | 'scroll';

  // Only for the 'click' trigger. A CSS selector of the element.
  triggerClickSelector?: string;

  // Only for the 'click' trigger. Whether to open the popup only on the first click. 
  triggerClickOnce?: boolean;

  // Only for the 'scroll' trigger. The amount of scroll expressed as 0..1 where 1 is 100% of the page.
  triggerScrollThreshold?: number;
}

Popup content

HTML

Provide a string (text or HTML) as content:

{
  content: 'Some <b>HTML</b>',
}

CSS selector

Use a CSS selector to get the content from the current page (only class and ID selectors are supported):

{
  content: '#my-popup',
}

External Svelte component

Load an external Svelte component from a remote URL or path:

{
  content: 'https://.../author/1.0/author-component.js',
}

Triggers

• exit

  The 'exit intent'. Triggers when the user is about to close the tab / window.

• enter

  Triggers upon entering the website.

• click

  Triggers when the user clicks on an element matching the selector specified in triggerClickSelector.

• scroll

  Triggers once the user scrolls at least the amount of the page specified in triggerScrollThreshold (as number 0..1, where 1 is 100%).

Tip: use the enter trigger and the delay option to automatically open the popup after a specified time on the page.

Tip: You can also open popups without triggers using wirypop.open(options: IPopupOptions).

Targeting

Popups can be targeted using a wide range of properties from the user‘s OS, language, time to the user‘s approximate geolocation.

Note: the geolocation is determined on the client from the user‘s time zone. WiryPop does not use IP addresses nor any external service.

{
  targeting: [{
    param: 'locale',
    values: ['en']
  }, {
    param: 'path',
    negate: true,
    values: ['/dont-show-here']
  }]
}

The conditions above are equal to if locale === 'en' and path !== '/dont-show-here'.

Available parameters:

• country

  The country code of the user as detected from the user‘s time zone. Use lowercase ISO 3166-1 alpha-2 codes such as us, uk, de etc.

• host

  The current hostname. Uses location.hostname.

• locale

  User language detected from navigator.language. Use lowercase ISO 639-1 2-letter codes such as en or full codes eu-us.

• path

  The current pathname. Uses location.pathname.

• platform

  The device platform (OS). Possible values are: android, ios, mac, linux, windows.

• queryparam

  Query parameter (?name=value). Matches only the existance of the parameter, not the value.

• region

  Geographic region detected from the user‘s time zone. Possible values as africa, america, antarctica, arctic, asia, atlantic, australia, europe, indian, pacific.

• time

  Use ISO dates in the format values: [ from, to ].

Event tracking

WiryPop can track events using wirypop.event(eventName: string). Recorded events will be submitted when you call wirypop.submit(). See below.

You can also provide custom parameters:

wirypop.event('custom-event', {
  someParam: 123,
  another: 'value',
})

Note: events are submitted only if Do Not Track is turned off on the user‘s device or disabled in the configuration.

Data submissions

Some popups support data submissions (e.g. contact form, feedback etc.) You can configure submitUrl which will perform POST ${submitUrl} with the submitted data in JSON format:

POST ${submitUrl}

{
  events: ['some-custom-event'],
  data: {
    feedback: '...',
    some: 'data'
  }
}

If you‘re developing a custom popup, use wirypop.submit(payload) to submit data:

wirypop.submit({
  events: [],
  data: {}
})

Don‘t have an API? Use our free submissions API: https://wiry.io

Create custom popups

WiryPop allows you to create your own popups with Svelte. Please note, the popup must follow a specific code structure.

More info: https://github.com/wiry-io/wirypop-starter

API

TODO: WiryPop API methods