@chekinapp/guest-sdk (Core Package)

The core framework-agnostic SDK package for integrating Chekin's guest registration and check-in platform into web applications through secure iframe embedding.

Overview

This package provides the foundational ChekinGuestSDK class that can be used in any JavaScript/TypeScript environment, regardless of framework. It handles iframe creation, secure communication via postMessage, configuration validation, and comprehensive logging.

Migrating from ChekinPro? See our comprehensive Migration Guide for step-by-step instructions to upgrade from the legacy ChekinPro SDK.

Key Features

• Framework Agnostic - Works with vanilla JS, React, Vue, Angular, Svelte, or any web framework
• Secure Iframe Embedding - Proper sandboxing and CSP compliance
• Smart URL Management - Handles query parameter limits with postMessage fallback
• Type-Safe Configuration - Full TypeScript support with runtime validation
• Event System - Comprehensive event handling for iframe communication
• Logging & Debugging - Built-in logger with remote log shipping capabilities
• Route Synchronization - Optional URL sync between parent and iframe

Installation

npm install @chekinapp/guest-sdk

Quick Start

import {ChekinGuestSDK} from '@chekinapp/guest-sdk';

const sdk = new ChekinGuestSDK({
  apiKey: 'your-api-key',
  reservationId: 'reservation-123',
  mode: 'ALL',
  autoHeight: true,
  onHeightChanged: height => console.log(`Height: ${height}px`),
  onGuestRegistered: guest => console.log('Guest registered:', guest),
});

// Render into a DOM element
await sdk.render('container-element-id');
// or
await sdk.render(document.getElementById('container'));

Core Architecture

ChekinGuestSDK Class (src/ChekinGuestSDK.ts)

Main SDK class providing:

• Iframe lifecycle management (creation, loading, destruction)
• Configuration validation and error handling
• Event system with type-safe callbacks
• Route synchronization capabilities
• Logger integration

Communication Layer (src/communication/)

• ChekinCommunicator - Handles bidirectional postMessage communication
• Message validation and origin checking
• Event dispatching and listener management

Utilities (src/utils/)

• formatChekinUrl.ts - Smart URL building with parameter limit handling
• validation.ts - Configuration validation with detailed error reporting
• ChekinLogger.ts - Comprehensive logging system with levels and remote shipping
• packageInfo.ts - Package metadata utilities

Types (src/types/)

• Complete TypeScript definitions for all SDK interfaces
• Event type definitions and callback signatures
• Configuration interfaces with JSDoc documentation

API Reference

Constructor

new ChekinGuestSDK(config: ChekinGuestSDKConfig & { logger?: ChekinLoggerConfig })

Methods

Complete Methods Reference

| Method | Parameters | Returns | Description | | ----------------- | ---------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------- | | render | container: string \| HTMLElement | Promise<HTMLIFrameElement> | Renders the SDK iframe into the specified container. Accepts element ID (string) or HTMLElement reference | | initialize | config: ChekinGuestSDKConfig | void | Initialize/update SDK configuration | | initAndRender | config & {targetNode: string} | Promise<HTMLIFrameElement> | Initialize and render in one call (backward compatibility) | | destroy | - | void | Destroys the SDK instance, removes iframe from DOM, and cleans up event listeners | | unmount | - | void | Legacy method, same as destroy() | | updateConfig | newConfig: Partial<ChekinGuestSDKConfig> | void | Updates SDK configuration and sends changes to iframe. Validates new config before applying | | on | event: string, callback: ChekinEventCallback | void | Adds event listener for SDK events. Supports all SDK event types with type-safe callbacks | | off | event: string, callback: ChekinEventCallback | void | Removes specific event listener. Must pass same callback reference used in on() |

Configuration

Complete Parameters Table

| Parameter | Type | Required | Default | Description | | --------------------------------- | ---------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey | string | ✅ | - | API key created in the Chekin dashboard | | mode | string | ❌ | 'ALL' | SDK mode: 'ALL' (full functionality), 'ONLY_GUEST_FORM' (guest registration only), 'IV_ONLY' (identity verification only), 'PROPERTY_LINK' (property selection) | | reservationId | string | ❌ | - | ID of specific reservation to pre-load in the SDK | | externalId | string | ❌ | - | External ID for PMS integrations. If both reservationId and externalId are provided, externalId takes priority | | guestId | string | ❌ | - | Specific guest ID. Can only be used in 'ONLY_GUEST_FORM' mode with reservationId or externalId | | housingId | string | ❌ | - | ID of the particular housing/property. Required for 'PROPERTY_LINK' mode only | | baseUrl | string | ❌ | - | Custom base URL for SDK hosting (for self-hosted deployments) | | version | string | ❌ | - | Pin to specific SDK version (e.g., '1.6.2'). If not provided, uses latest version | | defaultLanguage | string | ❌ | 'en' | Default interface language. Supported: 'en', 'es', 'el', 'uk', 'it', 'de', 'fr', 'hu', 'ru', 'cs', 'bg', 'pt', 'ro', 'et', 'pl', 'ca' | | styles | string | ❌ | - | CSS styles injected into the SDK iframe for custom theming | | stylesLink | string | ❌ | - | URL to external CSS stylesheet for advanced customization | | autoHeight | boolean | ❌ | true | Automatically adjust iframe height based on content | | enableLogging | boolean | ❌ | false | Enable SDK internal logging (logs are disabled by default) | | prefillData | object | ❌ | - | Pre-fill guest form data to reduce manual entry | | prefillData.guestForm | object | ❌ | - | Guest form pre-fill data (name, surname, email, etc.) | | enableGuestsRemoval | boolean | ❌ | false | Allow guests to be removed from reservations | | canEditReservationDetails | boolean | ❌ | true | Allow editing of reservation details | | canShareRegistrationLink | boolean | ❌ | false | Enable sharing of registration links | | routeSync | boolean | ❌ | false | Enable URL synchronization between parent and iframe | | onHeightChanged | function | ❌ | - | Callback when iframe height changes. Receives (height: number) | | onError | function | ❌ | - | Error callback. Receives (error: { message: string; code?: string }) | | onConnectionError | function | ❌ | - | Connection/network error callback. Receives (error: any) | | onGuestRegistered | function | ❌ | - | Callback when a guest completes registration. Receives guest data object | | onAllGuestsRegistered | function | ❌ | - | Callback when all guests in a reservation complete registration | | onReservationFound | function | ❌ | - | Callback when a reservation is successfully loaded | | onReservationFetched | function | ❌ | - | Callback when reservation fetch completes (success or failure). Receives {isSuccess: boolean} | | onReservationCreated | function | ❌ | - | Callback when a new reservation is created. Receives reservation object with ID | | onReservationFoundFromHousing | function | ❌ | - | Callback when reservation is found via housing search. Receives reservation object | | onIVFinished | function | ❌ | - | Callback when identity verification completes. Receives verification results | | onScreenChanged | function | ❌ | - | Callback when screen/route changes in SDK. Receives screen information |

Configuration Interface

interface ChekinGuestSDKConfig {
  // Required
  apiKey: string;

  // Optional Core Settings
  baseUrl?: string;
  version?: string;
  mode?: 'ALL' | 'ONLY_GUEST_FORM' | 'IV_ONLY' | 'PROPERTY_LINK';

  // Context
  reservationId?: string;
  externalId?: string;
  housingId?: string;
  guestId?: string;
  defaultLanguage?: string;

  // UI Customization
  styles?: string;
  stylesLink?: string;
  autoHeight?: boolean;
  prefillData?: {
    guestForm?: {
      name?: string;
      surname?: string;
      email?: string;
      // ... other guest form fields
    };
  };

  // Features
  enableGuestsRemoval?: boolean;
  canEditReservationDetails?: boolean;
  canShareRegistrationLink?: boolean;
  routeSync?: boolean;

  // Advanced
  enableLogging?: boolean;

  // Event Callbacks
  onHeightChanged?: (height: number) => void;
  onError?: (error: {message: string; code?: string}) => void;
  onConnectionError?: (error: any) => void;
  onGuestRegistered?: (guest: Guest) => void;
  onAllGuestsRegistered?: () => void;
  onReservationFound?: () => void;
  onReservationFetched?: (data: {isSuccess: boolean}) => void;
  onReservationCreated?: (reservation: {id: string}) => void;
  onReservationFoundFromHousing?: (reservation: {id: string}) => void;
  onIVFinished?: (details: IdentityVerificationDetails) => void;
  onScreenChanged?: (data: any) => void;
}

Configuration Examples

Basic Configuration:

{
  apiKey: 'pk_live_your_api_key',
  reservationId: 'reservation-123',
  mode: 'ALL',
  defaultLanguage: 'en'
}

Advanced Configuration:

{
  apiKey: 'pk_live_your_api_key',
  version: '1.6.2',
  reservationId: 'reservation-123',
  mode: 'ALL',
  defaultLanguage: 'es',
  styles: `
    .primary-button { background: #007cba; }
    .container { max-width: 800px; }
  `,
  autoHeight: true,
  enableLogging: true,
  prefillData: {
    guestForm: {
      name: 'John',
      surname: 'Doe',
      email: '[email protected]'
    }
  },
  onHeightChanged: (height) => console.log(`Height: ${height}px`),
  onError: (error) => console.error('SDK Error:', error),
  onGuestRegistered: (guest) => console.log('Guest registered:', guest)
}

Events

The SDK emits the following events:

• chekin:height-changed - Iframe content height changes
• chekin:error - Error occurs in SDK or iframe
• chekin:connection-error - Network or communication error
• chekin:guest-registered - Guest completes registration
• chekin:all-guests-registered - All guests complete registration
• chekin:reservation-found - Reservation successfully loaded
• chekin:reservation-fetched - Reservation fetch completes
• chekin:iv-finished - Identity verification completes
• chekin:screen-changed - Screen/route changes

Advanced Usage

Custom Event Handling

sdk.on('chekin:height-changed', height => {
  document.getElementById('container').style.height = `${height}px`;
});

sdk.on('chekin:error', error => {
  console.error('SDK Error:', error.message);
  // Handle error appropriately
});

sdk.on('chekin:guest-registered', guest => {
  console.log('Guest registered:', guest.name, guest.surname);
});

Configuration Updates

// Update configuration after initialization
sdk.updateConfig({
  reservationId: 'new-reservation-456',
  styles: 'body { background: #f5f5f5; }',
  enableLogging: true,
});

Framework Integration Examples

Vanilla JavaScript

<div id="chekin-container"></div>
<script>
  const sdk = new ChekinGuestSDK({
    apiKey: 'your-key',
    reservationId: 'reservation-123',
    mode: 'ALL',
  });
  sdk.render('chekin-container');
</script>

Vue.js

<template>
  <div ref="container" class="chekin-container"></div>
</template>

<script>
import {ChekinGuestSDK} from '@chekinapp/guest-sdk';

export default {
  mounted() {
    this.sdk = new ChekinGuestSDK({
      apiKey: 'your-key',
      reservationId: 'reservation-123',
      mode: 'ALL',
    });
    this.sdk.render(this.$refs.container);
  },
  beforeUnmount() {
    this.sdk?.destroy();
  },
};
</script>

Angular

import {Component, ElementRef, ViewChild, OnInit, OnDestroy} from '@angular/core';
import {ChekinGuestSDK} from '@chekinapp/guest-sdk';

@Component({
  template: '<div #container class="chekin-container"></div>',
})
export class ChekinComponent implements OnInit, OnDestroy {
  @ViewChild('container', {static: true}) container!: ElementRef;
  private sdk!: ChekinGuestSDK;

  ngOnInit() {
    this.sdk = new ChekinGuestSDK({
      apiKey: 'your-key',
      reservationId: 'reservation-123',
      mode: 'ALL',
    });
    this.sdk.render(this.container.nativeElement);
  }

  ngOnDestroy() {
    this.sdk?.destroy();
  }
}

Development

Building

# Build the package
npm run build

# Development mode with watching
npm run dev

Testing

The core package includes comprehensive tests for all functionality. Use the sandbox.html file for manual testing during development.

Security

• All iframe communication uses secure postMessage protocol
• Origin validation ensures communication only with trusted domains
• API keys are validated but never logged in plain text
• CSP-compliant iframe sandboxing prevents malicious code execution

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+
• No Internet Explorer support

Related Packages

• @chekinapp/guest-sdk-react - React components and hooks built on this core package