SDK Reference

Complete reference for the Rowporter JavaScript SDK.

Installation

Script Tag (Recommended)

html

<script src="https://rowporter.com/embed.js"></script>

NPM (Coming Soon)

bash

npm install @rowporter/sdk

Rowporter.init(config)

Initialize the SDK with your configuration. Must be called before any other methods.

Configuration Options

Option	Type	Default	Description
templateId	string	required	Your template ID from the dashboard
baseUrl	string	rowporter.com	Base URL of Rowporter service
modal	boolean	true	Show widget in modal overlay
container	string \| Element	null	Container for inline embed mode
width	string	'100%'	Widget width (inline mode)
height	string	'600px'	Widget height (inline mode)
modalWidth	string	'900px'	Modal width
modalHeight	string	'700px'	Modal height
closeOnComplete	boolean	false	Auto-close modal on complete
closeOnCancel	boolean	true	Auto-close modal on cancel
theme	object	{}	Theme customization (see below)
locale	string	'en'	Language: en, es, fr, de, pt, it, nl, ja, zh, ko
metadata	object	null	Custom data to include with import
user	object	null	User info: {id, email, name}
skipSheetSelection	boolean	false	Auto-select first sheet for multi-sheet Excel files

Example

javascript

Rowporter.init({
  templateId: 'tpl_abc123',
  modal: true,
  modalWidth: '800px',
  modalHeight: '600px',
  closeOnComplete: true,
  locale: 'en',
  
  // Custom metadata (passed to webhooks)
  metadata: {
    source: 'onboarding',
    campaign: 'q1-2024'
  },
  
  // User info for personalization
  user: {
    id: 'user-123',
    email: 'user@example.com',
    name: 'John Doe'
  },
  
  // Theme customization
  theme: {
    primaryColor: '#3B82F6',
    borderRadius: '8px'
  },
  
  // Callbacks (onComplete and onError are highly recommended)
  onReady: () => console.log('Widget ready'),
  onComplete: (result) => {
    console.log('Import complete', result);
    // result.data - array of imported rows
    // result.totalRows - total row count
  },
  onError: (error) => {
    console.error('Import error', error);
  },
  onCancel: () => console.log('Import cancelled')
});

Callbacks

onReady()

Called when the widget is fully loaded and ready to use.

javascript

onReady: () => {
  console.log('Widget is ready');
}

onUploadStart(payload)

Called when a file upload begins.

javascript

onUploadStart: (payload) => {
  console.log('File:', payload.fileName);
  console.log('Size:', payload.fileSize);
  console.log('Type:', payload.fileType);
}

onSheetsDetected(payload)Excel Only

Called when multiple sheets are detected in an Excel file.

javascript

onSheetsDetected: (payload) => {
  console.log('Total sheets:', payload.totalSheets);
  console.log('Sheet names:', payload.sheets);
  // [{name: 'Sheet1', rowCount: 100, columnCount: 5}, ...]
}

onSheetSelected(payload)Excel Only

Called when the user selects a sheet from a multi-sheet Excel file.

javascript

onSheetSelected: (payload) => {
  console.log('Selected sheet:', payload.sheetName);
  console.log('Sheet index:', payload.sheetIndex);
}

onMappingComplete(payload)

Called when column mapping is confirmed by the user.

javascript

onMappingComplete: (payload) => {
  console.log('Mappings:', payload.mappings);
  // [{sourceColumn: 'Email', targetColumn: 'email', confidence: 0.95, isAutoMatched: true}]
  console.log('Unmapped columns:', payload.unmappedColumns);
}

onComplete(payload)Most Important

Called when the import is successfully completed. Contains all imported data.

javascript

onComplete: (result) => {
  console.log('Import ID:', result.importId);
  console.log('Template ID:', result.templateId);
  console.log('File name:', result.fileName);
  console.log('Total rows:', result.totalRows);
  console.log('Valid rows:', result.validRows);
  console.log('Skipped rows:', result.skippedRows);
  console.log('Columns:', result.columns);
  console.log('Metadata:', result.metadata);
  
  // The imported data
  console.log('Data:', result.data);
  // [{email: 'john@example.com', name: 'John Doe', ...}, ...]
  
  // Send to your backend
  fetch('/api/import', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      importId: result.importId,
      data: result.data
    })
  });
}

onCancel()

Called when the user cancels the import.

javascript

onCancel: () => {
  console.log('User cancelled the import');
}

onError(payload)

Called when an error occurs.

javascript

onError: (error) => {
  console.error('Error code:', error.code);
  console.error('Error message:', error.message);
  console.error('Details:', error.details);
}

Methods

Rowporter.open()

Open the modal widget. Only works in modal mode.

Rowporter.close()

Close the modal widget.

Rowporter.render(container)

Render the widget in a specific container (inline mode).

javascript

Rowporter.render('#my-container');
// or
Rowporter.render(document.getElementById('my-container'));

Rowporter.destroy()

Destroy the widget and clean up all resources.

Rowporter.setTheme(theme)

Update the widget theme at runtime.

javascript

Rowporter.setTheme({
  primaryColor: '#10B981',
  backgroundColor: '#F9FAFB'
});

Rowporter.setLocale(locale)

Change the widget language at runtime.

javascript

Rowporter.setLocale('es'); // Spanish
Rowporter.setLocale('fr'); // French
Rowporter.setLocale('de'); // German
Rowporter.setLocale('pt'); // Portuguese

Rowporter.isOpen()

Returns true if the modal is currently open.

Rowporter.isInitialized()

Returns true if the SDK has been initialized.

Rowporter.getConfig()

Returns the current configuration object. Useful for debugging.

Rowporter.getBaseUrl()

Returns the base URL being used by the SDK.

Rowporter.reinit(config)

Re-initialize with a new configuration. Automatically calls destroy() first.

javascript

// Switch to a different template
Rowporter.reinit({
  templateId: 'new-template-id',
  onComplete: (result) => console.log(result),
  onError: (error) => console.error(error)
});

Rowporter.bindButton(selector)

Safely bind a button to open the importer. Handles DOM timing automatically - no need for DOMContentLoaded.

javascript

// Bind by selector
Rowporter.bindButton('#import-button');

// Or bind by element
Rowporter.bindButton(document.querySelector('.my-btn'));

data-rowporter-open

Auto-bind any element with this attribute. No JavaScript needed for the button - just add the attribute.

html

<!-- Simplest way to add an import button -->
<button data-rowporter-open>Import Data</button>

<!-- Works on any element -->
<a href="#" data-rowporter-open>Import CSV</a>

Theme Options

Customize the widget appearance to match your brand.

Property	Type	Description
primaryColor	string	Primary brand color (buttons, links)
primaryHoverColor	string	Primary color on hover
backgroundColor	string	Widget background color
textColor	string	Main text color
borderColor	string	Border and divider color
errorColor	string	Error message color
successColor	string	Success message color
fontFamily	string	Font family
borderRadius	string	Border radius for elements

Example

javascript

Rowporter.init({
  templateId: 'tpl_abc123',
  theme: {
    primaryColor: '#8B5CF6',      // Purple
    primaryHoverColor: '#7C3AED',
    backgroundColor: '#FFFFFF',
    textColor: '#1F2937',
    borderColor: '#E5E7EB',
    errorColor: '#EF4444',
    successColor: '#10B981',
    fontFamily: '"Inter", sans-serif',
    borderRadius: '12px'
  },
  onComplete: (result) => console.log(result),
  onError: (error) => console.error(error)
});

Duplicate Detection (Idempotency)

Rowporter automatically detects duplicate file imports to prevent accidental re-imports. When a duplicate is detected, users see a warning and can choose to proceed or cancel.

How it works

• File content is hashed using SHA-256
• Duplicates are detected within a configurable window (default: 7 days)
• Users see the original import date and can choose to proceed
• Duplicate imports are linked to the original for audit purposes

onDuplicate(payload)New

Called when a duplicate file is detected. Return true to proceed with the import, or false to cancel.

javascript

onDuplicate: (payload) => {
  console.log('Duplicate detected!');
  console.log('Original import:', payload.existingImport.id);
  console.log('Imported on:', payload.existingImport.importedAt);
  console.log('Row count:', payload.existingImport.rowCount);
  
  // Return true to proceed anyway, false to cancel
  return confirm('This file was already imported. Import again?');
}

forceImport

Set to true to skip duplicate detection entirely.

javascript

Rowporter.init({
  templateId: 'tpl_abc123',
  forceImport: true, // Skip duplicate detection
  onComplete: (result) => console.log(result)
});

Sandbox Mode

Test imports safely without affecting production data. Sandbox mode uses separate API keys and webhook URLs.

Key Features

• Sandbox API keys: sk_sandbox_...
• Production API keys: sk_live_...
• Sandbox imports never trigger production webhooks
• Unlimited sandbox imports (no quota consumption)

environment

Specify the environment for imports.

javascript

Rowporter.init({
  templateId: 'tpl_abc123',
  environment: 'sandbox', // or 'production' (default)
  onComplete: (result) => {
    console.log('Environment:', result.environment);
  }
});

Localization

The widget supports multiple languages out of the box.

Supported Languages

English

Spanish

French

German

Portuguese

Italian

Dutch

Japanese

Chinese

Korean

← API Reference Webhooks