Install

Package

# npm
$ npm i @oktus/pixel

# yarn
$ yarn add @oktus/pixel

# pnpm
$ pnpm add @oktus/pixel

# bun
$ bun add @oktus/pixel

CDN

<script src="https://docs.oktus.io/scripts/pixel.min.js" data-pixel="YOUR_PIXEL_ID"></script>

Usage

import { Pixel } from '@oktus/pixel'

const pixel = await Pixel.setup({
  pixelId: 'YOUR_PIXEL_ID'
})

// If you have included the package with a <script> tag, you can access your pixel instance via the global scope
// e.g. window.pixel.version

Webchat

The webchat resource allows you to interact with your webchat programmatically.

Examples

// Toggle the webchat (open if closed, close if open)
pixel.webchat.toggle()

// Open the webchat
pixel.webchat.open()

// Close the webchat
pixel.webchat.close()

// Send a message
pixel.webchat.sendMessage({
  message: 'Hello, this is an outgoing message!'
})

// Update configuration dynamically
pixel.webchat.update({
  theme: 'dark',
  colors: {
    primary: '#FF5733',
    secondary: '#4287f5'
  },
  positioning: {
    position: 'bottom-right',
    offset: {
      x: 20,
      y: 20
    },
    toggle: {
      width: 60,
      height: 60,
      borderRadius: 30
    }
  }
})

Triggers

The triggers resource allows you to define actions that execute based on specific events or conditions on your website.

Available Triggers

• timeout: Execute an action after a specific time delay
• onLoad: Execute an action when the page loads
• onClick: Execute an action when a user clicks anywhere on the page
• queryParam: Execute an action when a specific query parameter is present in the URL

Examples

// Create a trigger that shows a popup after 5 seconds
pixel.triggers.trigger({
  type: 'timeout',
  delay: 5000,
  action: {
    type: 'openPopup',
    url: 'https://forms.oktus.io/contact',
    width: 500,
    height: 600
  }
})

// Create a trigger that redirects when a specific query parameter is present
pixel.triggers.trigger({
  type: 'queryParam',
  queryKey: 'campaign',
  queryValue: 'summer2025',
  action: {
    type: 'openUrl',
    url: 'https://example.com/special-offer'
  }
})

// Close all currently open popups
pixel.triggers.closeAllPopups()

Interactions

The Interactions resource enables tracking user behavior and executing actions based on predefined events.

Examples

// Track a custom event
pixel.interactions.handleEvent(
  {
    type: 'userAction',
    pushUpdates: true
  },
  {
    actionType: 'buttonClick',
    elementId: 'signup-button',
    timestamp: Date.now()
  }
)

// Execute an action linked to an event
pixel.interactions.handleEvent(
  {
    type: 'userAction',
    executeRef: 'special-offer-popup'
  },
  {
    actionType: 'offerViewed',
    timestamp: Date.now()
  }
)

Contributing

Instructions

Contact

If you'd like to get in touch or have any further questions, feel free to either join our Discord or start a new discussion!