Dashboard

Advanced Integration

Welcome to the Signalbit JS API Documentation. Here you'll find a complete overview of the functions currently available in our JavaScript API. As new features are released, they will be added to this documentation.

If you need assistance with the JS API or encounter any problems during integration, feel free to reach out to us at api@signalbit.com

To learn more about a specific function, click its name under the Resources section - this will take you to detailed documentation along with usage examples.

Installation

Include the Signalbit script in your HTML: 

<script src="signalbit-v1.js" data-signalbit-uuid="your-uuid-here"></script>

Quick Start

// Initialize Signalbit
  await signalbit.init();

  // Subscribe to notifications
  await signalbit.subscribe();

  // Send a test notification
  await signalbit.sendNotification({
    title: "Hello World!",
    message: "This is a test notification"
  });

API Reference

Core Initialization

init(config)

Initializes the Signalbit service with the provided configuration. This function sets up the service by verifying the domain, checking browser support, getting configuration data, detecting client information, and optionally showing the subscription box if auto-opt-in is enabled.

Parameters:
  • init(config)(Object, optional): Configuration object for service worker settings
Example:
await signalbit.init({
  registerServiceWorkerOnLoad: true,
  serviceWorkerPath: '/signalbit-sw.js',
  serviceWorkerScope: '/'
});

verifyDomain(signalbitUuid, domainName)

Checks if the current domain is verified and authorized to use the Signalbit service. Returns domain verification status and ID if successful.

Parameters:
  • signalbitUuid (String): Unique identifier for the Signalbit installation
  • domainName (String): Domain name to verify/li>
Returns: Promise resolving to verification result object

getConfig(signalbitUuid, domainId)

Retrieves the Signalbit configuration for the specified domain. The configuration includes the app server public key and auto-opt-in settings. Results are cached in localStorage for 15 minutes.

Parameters:
  • signalbitUuid (String): Unique identifier for the Signalbit installation
  • domainId (String): Domain ID from verification
Returns: Promise resolving to configuration object

Subscription Management

initSubscription()

Sets up push notification subscription by registering the service worker and checking for existing subscriptions. This is the main entry point for enabling push notifications.

Returns: Promise resolving to boolean

subscribePush()

Requests notification permission from the user and creates a push subscription if permission is granted. Sends subscription data to the service worker for processing.

Returns: Promise

initUnsubscribe()

Prepares the service for unsubscribing from push notifications by registering the service worker.

Returns: Promise

unsubscribe()

Removes the current push notification subscription and updates the permission status to denied in localStorage.

Returns: Promise

getSubscriptionState()

Returns the current subscription permission state (granted, denied, or default) from localStorage.

Returns: String - Current permission state

Service Worker

initSW(serviceWorkerPath, serviceWorkerScope)

Registers the Signalbit service worker with the specified path and scope. Returns the service worker registration object.

Parameters:
  • serviceWorkerPath (String): Path to the service worker file
  • serviceWorkerScope (String, default: "/"): Scope for the service worker
Returns: Promise resolving to service worker registration

UI Components

initSubscriptionBox()

Initializes the subscription popup box by fetching custom popup data, applying styles, and triggering the box display.

Returns: Promise

triggerSubscriptionBox(trigger, callbackFunc)

Handles different triggers for showing the subscription box. Currently supports 'on-landing' trigger.

Parameters:
  • trigger (String): Trigger type ('on-landing')
  • callbackFunc (Function): Callback function to execute

createSubscriptionBox()

Creates the HTML elements for the subscription popup including overlay, box container, and event handlers for allow/deny buttons.

Returns: Promise

showSubscriptionBox()

Displays the subscription popup by adding CSS classes to make it visible with animation.

Returns: Promise

hideSubscriptionBox()

Hides the subscription popup by removing CSS classes and making it invisible.

Returns: Promise

appendStyles()

Adds the CSS styles for the subscription box to the document head.

Customization

getCustomPopup()

Fetches custom popup configuration data from the API for the current domain, including custom styling and text content.

Returns: Promise resolving to a popup configuration object

transformCSSVariables(themeData)

Updates the CSS styles for the subscription box using custom theme data like colors, backgrounds, and button styles.

Parameters:
  • themeData (Object): Theme configuration object

transformBoxHTML(themeData)

Updates the HTML content of the subscription box using custom theme data for titles, descriptions, and button text.

Parameters:
  • themeData (Object): Theme configuration object

Data Management

getIpData(names)

Retrieves IP address information including IP, city, and country from an external service. Returns an object with the requested data fields.

Parameters:
  • names (Array, default: ['ip', 'city', 'country']): Array of data fields to retrieve
Returns: Promise resolving to an IP data object

setExternalId(externalId)

Associates an external ID with the current subscriber and stores it both locally and on the server for tracking purposes.

Parameters:
  • externalId (String): External identifier to associate with the subscriber

setTags(tags)

Sets custom tags for the current subscriber to enable targeted messaging and segmentation.

Parameters:
  • tags (Array): Array of tag strings
Returns: Promise

Utilities

getStorageKey(key)

Creates a namespaced storage key by prefixing 'signalbit-' to the provided key name.

Parameters:
  • key (String): Base key name
Returns: String - Namespaced storage key

getOrCreateSubscriberId()

Generates or retrieves a unique subscriber ID. Creates a new ID using timestamp and random string if none exists, and stores it in localStorage.

Returns: String - Unique subscriber ID

generateRandomString(length)

Creates a random alphanumeric string of the specified length for generating unique identifiers.

Parameters:
  • length (Number): Length of the random string
Returns: String - Random alphanumeric string

setCookie(name, value, domain, days)

Sets a cookie with the specified name, value, domain, and expiration time. Uses secure settings for cross-site compatibility.

Parameters:
  • name (String): Cookie name
  • value (String): Cookie value
  • domain (String): Cookie domain
  • days (Number): Expiration time in days

getCookie(name)

Retrieves the value of a cookie by its name. Returns null if the cookie doesn't exist.

Parameters:
  • name (String): Cookie name
Returns: String|null - Cookie value or null

Notifications

sendNotification(subscriberId, payloadData)

Sends a test notification to a specific subscriber. Uses default notification content if no payload data is provided.

Parameters:
  • subscriberId (String): Target subscriber ID
  • payloadData (Object, optional): Notification payload with title, body, and url
Returns: Promise

Properties

PROPERTYTYPEDESCRIPTION

apiUrl

StringBase URL for Signalbit API endpoints

appServerPublicKey

StringPublic key for push notification encryption

subscriberId

StringUnique identifier for the current user

domainId

StringID of the verified domain

signalbitUuid

StringUnique identifier for the Signalbit installation

autoOptInBox

BooleanWhether to automatically show the subscription popup

permission

StringCurrent notification permission status

browser

StringBrowser name

browserVersion

NumberBrowser version number

deviceType

StringType of device (Desktop/Mobile)

os

StringOperating system name

osVersion

StringOperating system version

language

StringUser's language preference

timezone

StringUser's timezone

ip

StringUser's IP address

city

StringUser's city

country

StringUser's country

boxHTML

StringHTML template for the subscription popup

css

StringCSS styles for the subscription popup

swConfig

ObjectService worker configuration settings

Examples

Basic Setup
const signalbit = new Signalbit();
await signalbit.init();
Custom Configuration
const signalbit = new Signalbit();
await signalbit.init({
  registerServiceworkerOnLoad: false,
  serviceWorkerPath: '/my-custom-sw.js',
  serviceWorkerScope: '/notifications'
});
Set User Tags
await signalbit.setTags(['premium-user', 'newsletter-subscriber']);
Set External ID
await signalbit.setExternalId('user-12345');
Check Subscription Status
const status = signalbit.getSubscriptionState();
console.log('Permission:', status); // 'granted', 'denied', or 'default'
Send Custom Notification
await signalbit.sendNotification(subscriberId, {
  title: "Special Offer!",
  body: "Get 50% off on all products today",
  url: "https://example.com/sale"
});

On this Page