SDK Integration Overview¶

!!! info "TL;DR" Embed Canviq surveys in your app or website using the JavaScript SDK. Initialize with your API key, trigger surveys based on user actions, and optionally associate responses with user IDs. Native SDKs for all other platforms are in development.

Supported Platforms¶

Recommended integration path: Use the JavaScript SDK (@canviq/sdk-js) for all web integrations while native SDKs are in development. It supports all modern frameworks via a plain script tag or npm package.

Core Capabilities¶

The JavaScript SDK provides:

1. Survey Display — Show surveys as modals, slide-ins, or inline components
2. Targeting — Control when and where surveys appear based on user behavior
3. User Association — Link responses to user IDs for personalized follow-ups
4. Offline Support — Queue responses locally and sync when online
5. Localization — Automatic language detection or manual locale override
6. Accessibility — Keyboard navigation, screen reader support, and WCAG compliance

Quick Start (JavaScript)¶

Installation¶

npm install @canviq/sdk-js

Initialization¶

import { CanviqSDK } from '@canviq/sdk-js'

CanviqSDK.init({
  apiKey: 'your-api-key', // Required: Get from Admin → Settings → API Keys
  userId: 'user-123', // Optional: Associate responses with a user
  locale: 'en', // Optional: Force a specific locale (auto-detected by default)
  debug: false, // Optional: Enable debug logging
})

Show a Survey¶

// Show immediately
CanviqSDK.showSurvey('survey-id')

// Show after a delay
CanviqSDK.showSurvey('survey-id', {
  delay: 5000, // 5 seconds
})

// Show after a specific event
document.getElementById('export-button').addEventListener('click', () => {
  CanviqSDK.showSurvey('survey-id', {
    trigger: 'export_clicked',
    metadata: { format: 'pdf', size: 'large' },
  })
})

User Identification¶

// Identify user after login
CanviqSDK.identify('user-123', {
  email: 'user@example.com',
  name: 'Jane Doe',
  role: 'premium',
  signupDate: '2026-01-15',
})

// Update user properties
CanviqSDK.updateUser({
  lastActiveDate: new Date().toISOString(),
  featureUsageCount: 42,
})

// Clear user on logout
CanviqSDK.reset()

Widget Customization¶

CanviqSDK.showSurvey('survey-id', {
  style: 'modal', // 'modal' | 'slide-in' | 'inline'
  position: 'bottom-right', // For slide-in: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  zIndex: 9999, // CSS z-index for modal/slide-in
  theme: 'dark', // 'light' | 'dark' | 'auto'
})

React¶

🔜 Coming Soon — The React SDK (@canviq/sdk-react) is not yet available. In the meantime, use @canviq/sdk-js directly in your React app. A tracking issue will be opened when work begins.

iOS (Swift)¶

CanviqSDK is available via Swift Package Manager and CocoaPods. Requires iOS 15+, Swift 5.9+, Xcode 15+.

Swift Package Manager (recommended)

In Xcode: File > Add Package Dependencies, enter:

https://github.com/Revoir-Software/canviq-ios-sdk

Set the rule to Up to Next Major Version from 0.1.0.

CocoaPods

pod 'CanviqSDK', '~> 0.1'

Initialization (call once at app launch, before any screens appear):

import CanviqSDK

CanviqSDK.shared.initialize(
    apiKey: "cvq_live_your_key_here",
    userId: currentUser?.id
)

Tracking events (surveys are shown automatically when trigger conditions match):

CanviqSDK.shared.track("completed_onboarding")

For full integration details, see the iOS SDK documentation.

Android (Kotlin)¶

🔜 Coming Soon — The Android SDK (com.canviq:sdk-android) is not yet available. The Gradle artifact is not published. Track progress: Android SDK tracking issue.

React Native¶

🔜 Coming Soon — The React Native SDK (@canviq/sdk-react-native) is not yet available. Track progress: React Native SDK tracking issue.

Flutter¶

🔜 Coming Soon — The Flutter SDK (canviq_sdk) is not yet available. Track progress: Flutter SDK tracking issue.

Detailed Platform Guides¶

• JavaScript SDK Documentation
• iOS SDK — Getting Started
• iOS SDK — API Reference
• iOS SDK — Troubleshooting

Android, React Native, Flutter, React, Vue, and Angular guides will be published when each SDK ships.

Common Patterns¶

Post-Purchase Survey¶

// After successful checkout
CanviqSDK.showSurvey('post-purchase-survey', {
  delay: 10000, // Wait 10 seconds
  metadata: {
    orderId: '12345',
    total: 99.99,
    items: 3,
  },
})

Feature Usage Survey¶

// After user exports a file
CanviqSDK.showSurvey('export-feedback', {
  trigger: 'export_completed',
  metadata: { format: 'pdf', fileSize: '5MB' },
  maxShownCount: 1, // Only show once per user
})

Churn Prevention Survey¶

// Show to users who haven't logged in for 14 days
if (daysSinceLastLogin > 14) {
  CanviqSDK.showSurvey('churn-prevention', {
    style: 'modal',
    dismissable: false, // Force interaction
  })
}

Troubleshooting¶

Survey Not Appearing¶

1. Check API Key — Verify your API key is correct in the SDK initialization
2. Check Survey Status — Ensure the survey is published (not in draft mode)
3. Check Targeting Rules — Verify the user meets targeting criteria
4. Check Fatigue Rules — User may have already seen too many surveys recently
5. Check Console — Enable debug mode and check browser/app console for errors

Responses Not Saving¶

1. Check Network — Ensure the device has internet connectivity (or wait for offline sync)
2. Check API Key Permissions — Verify your API key has survey:response:write scope
3. Check User ID — If required, ensure a valid user ID was provided

Localization Issues¶

1. Check Locale Code — Ensure locale is in BCP 47 format (e.g., en, es, pt-BR)
2. Check Survey Translations — Verify the survey has translations for the target locale
3. Check Auto-Detection — If not manually set, SDK uses browser/device language

What's Next¶

• Creating Surveys — Build your first survey
• Distribution — Learn about targeting and fatigue management
• Analytics — Track survey performance and sentiment