SDK Reference

Complete reference for the Rowporter JavaScript SDK.

Installation

Script Tag (Recommended)

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

NPM (Coming Soon)

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.io	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
metadata	object	null	Custom data to include with import
user	object	null	User info: {id, email, name}

Example

Rowporter.init({
  templateId: 'tpl_abc123',
  modal: true,
  modalWidth: '800px',
  modalHeight: '600px',
  closeOnComplete: true,
  locale: 'en',
  
  // Custom metadata
  metadata: {
    source: 'onboarding',
    campaign: 'q1-2024'
  },
  
  // User info
  user: {
    id: 'user-123',
    email: 'user@example.com',
    name: 'John Doe'
  },
  
  // Theme customization
  theme: {
    primaryColor: '#3B82F6',
    borderRadius: '8px'
  },
  
  // Callbacks
  onReady: () => console.log('Widget ready'),
  onComplete: (result) => console.log('Import complete', result),
  onCancel: () => console.log('Import cancelled'),
  onError: (error) => console.error('Error', error)
});

Callbacks

onReady()

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

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

onUploadStart(payload)

Called when a file upload begins.

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

onUploadProgress(payload)

Called during file processing with progress updates.

onUploadProgress: (payload) => {
  console.log('Progress:', payload.progress + '%');
  console.log('Stage:', payload.stage); // 'parsing' | 'validating' | 'processing'
  console.log('Rows processed:', payload.rowsProcessed);
}

onMappingComplete(payload)

Called when column mapping is confirmed by the user.

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

onValidationComplete(payload)

Called when data validation completes.

onValidationComplete: (payload) => {
  console.log('Total rows:', payload.totalRows);
  console.log('Valid rows:', payload.validRows);
  console.log('Error rows:', payload.errorRows);
  console.log('Errors:', payload.errors);
  // [{row: 5, column: 'email', message: 'Invalid email', value: 'not-an-email'}]
}

onComplete(payload)Most Important

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

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.

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

onError(payload)

Called when an error occurs.

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).

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.

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

Rowporter.setLocale(locale)

Change the widget language at runtime.

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.

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

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'
  }
});

Localization

The widget supports multiple languages out of the box.

Supported Languages

English

Spanish

French

German

Portuguese

← API Reference Webhooks