Terminology

This document defines the terminology for Claspo Plugin SDK documentation.

Core Concepts

Widget

Interactive UI element displayed on end-user websites. Widgets collect data, show promotions, gather feedback, or display information.

Appearance

Visual state of a widget for a specific viewport (desktop or mobile). Each widget can have multiple appearances.

Appearance Model

JSON object representing the complete visual configuration of a widget. Output of the Claspo Editor, input for Widget Display SDK. Also referred to as Document Model.

View

A page or step within a widget. Widgets can contain multiple views for multi-step flows (e.g., form → thank you page).

SDKs and Packages

Claspo Editor

Drag-and-drop widget editor hosted on Claspo CDN. Does not require technical expertise. Outputs JSON Appearance Model.

• Does not allow custom HTML/CSS editing
• Builds reusable components instead
• Fully customizable widget layout, structure, and appearance
• Accessed via window['ClaspoEditor'].init(config)

Widget Display SDK

JavaScript SDK that renders widgets on end-user websites. Consumes Appearance Model and widget configuration, displays widgets, and emits user interaction events.

• Main entry: STATIC_RESOURCES_URL/script.esm.js
• Provides WidgetAPI class
• Manages widget display state
• Emits events: visibility, click, data submit, widget close

Component SDK

Bridge between Claspo Editor and Components. Transforms user choices into code parameters, manages widget data, handles inter-component interaction, and processes dynamic data.

Display Rules SDK

UI components that configure targeting rules stored as JSON. Widget Display SDK consumes these rules to determine when and where to display widgets to end users.

Editor Extensions

SDK for customizing editor panels and UI elements.

NPM Packages

@claspo/common

Shared TypeScript types and utilities used across all Claspo packages.

@claspo/editor

Editor SDK providing TypeScript types for widget integration, including LayoutType, WidgetType, and configuration interfaces.

@claspo/renderer

Core Web Components rendering engine. Provides:

• Base classes: WcElement, WcControlledElement
• Action system
• Form management
• Services
• View routing

@claspo/document-connector

SDK connection layer for managing widget layouts, positioning, events, and resource loading in host documents.

Components

Component

JavaScript class extending browser-native WebComponent (via WcElement base class). Renders UI elements within widgets.

Manifest

Component configuration object defining:

• Props (properties)
• Styles
• Events
• i18n (internationalization keys)

WcElement

Base class from @claspo/renderer that all components extend. Provides lifecycle methods, state management, and event handling.

Widget Layout

Types of widget display formats:

Widget Types

Functional categories of widgets:

Placements

Configuration for built-in widget insertion:

{
  selector: '#widget',      // CSS selector
  insertType: 'AFTER_BEGIN' // BEFORE_BEGIN | AFTER_BEGIN | BEFORE_END | AFTER_END | REPLACE
}

Configuration

Static Resources

Self-hosted bundle files required for widget display on end-user websites. Contents of site-scripts/bundle.zip must be hosted from the same domain as the customer's script.

Editor Init Config

Configuration object passed to ClaspoEditor.init() including:

• authToken - Authentication token
• containerElement - HTML element for editor
• editorScriptsUrl - Claspo CDN URL
• staticResourcesUrl - Customer-hosted resources URL
• api - HTTP API handlers
• theme - Visual customization

Theming

Editor visual customization system allowing brand colors, fonts, and UI element styling.

Contact Fields

Form field mapping configuration connecting widget inputs to customer data fields.

Multilanguage

Widget localization system:

• Editor: Configures widgets for multiple languages, provides AI-powered translations
• Widget Display SDK: Detects end-user language, requests appropriate localization

Prize Pool Manager

Gamification configuration system:

• Editor: Configures promocodes, prizes, winning probabilities
• Widget Display SDK: Fetches and distributes prizes to users

Actions

User interaction handlers within widgets:

Events

Widget lifecycle events emitted by Widget Display SDK:

Integration Variables

API Classes

WidgetAPI

Main JavaScript class for managing website widgets:

import { WidgetAPI } from 'STATIC_RESOURCES_URL/script.esm.js';

const api = new WidgetAPI({ staticResourcesUrl: 'STATIC_RESOURCES_URL' });
api.showWidget(documentModel, widgetConfig);

ClaspoEditor

Global editor instance:

window['ClaspoEditor'].init(config, successCallback, errorCallback);
window['ClaspoEditor'].destroy();
window['ClaspoEditor'].save();
window['ClaspoEditor'].cancel();