@oktus/pixel

Pixel is the ultimate tool for website owners on the Oktus platform. With Pixel, you can effortlessly integrate webchat and powerful website analytics directly into your site. Stay connected with your visitors in real-time and gain valuable insights into their behavior.

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 module 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 module 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 module 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!