Skip to content

SDK Integration Overview

!!! info "TL;DR" Embed Canviq surveys in your app or website using platform-specific SDKs. Supports JavaScript, React, iOS, Android, React Native, and Flutter. Initialize with your API key, trigger surveys based on user actions, and optionally associate responses with user IDs.

Supported Platforms

Canviq provides native SDKs for all major platforms:

Platform Package Status
JavaScript @canviq/sdk-js ✅ Stable
React @canviq/sdk-react ✅ Stable
iOS (Swift) CanviqSDK (CocoaPods, SPM) ✅ Stable
Android (Kotlin) com.canviq:sdk-android ✅ Stable
React Native @canviq/sdk-react-native ✅ Stable
Flutter canviq_sdk ✅ Stable
Vue @canviq/sdk-vue 🚧 Beta
Angular @canviq/sdk-angular 🚧 Beta

Each SDK is maintained in the Canviq SDK Monorepo using Turborepo and Changesets for versioned releases.

Core Capabilities

All SDKs provide:

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

Quick Start (React)

Installation

npm install @canviq/sdk-react

Provider Setup

import { CanviqProvider } from '@canviq/sdk-react'

function App() {
  return (
    <CanviqProvider apiKey="your-api-key" userId="user-123" locale="en">
      <YourApp />
    </CanviqProvider>
  )
}

Trigger Survey

import { useSurvey } from '@canviq/sdk-react'

function ExportButton() {
  const { showSurvey } = useSurvey()

  const handleExport = () => {
    // Your export logic
    showSurvey('survey-id', {
      trigger: 'export_clicked',
      metadata: { format: 'pdf' },
    })
  }

  return <button onClick={handleExport}>Export PDF</button>
}

Inline Survey Component

import { Survey } from '@canviq/sdk-react'

function FeedbackPage() {
  return (
    <div>
      <h1>We'd love your feedback</h1>
      <Survey surveyId="survey-id" style="inline" />
    </div>
  )
}

Quick Start (iOS)

Installation (CocoaPods)

pod 'CanviqSDK'

Initialization

import CanviqSDK

CanviqSDK.shared.initialize(
    apiKey: "your-api-key",
    userId: "user-123",
    locale: "en"
)

Show Survey

// Show immediately
CanviqSDK.shared.showSurvey(surveyId: "survey-id")

// Show after user action
@IBAction func exportButtonTapped(_ sender: UIButton) {
    CanviqSDK.shared.showSurvey(
        surveyId: "survey-id",
        trigger: "export_clicked",
        metadata: ["format": "pdf"]
    )
}

User Identification

// Identify user after login
CanviqSDK.shared.identify(
    userId: "user-123",
    properties: [
        "email": "user@example.com",
        "name": "Jane Doe",
        "role": "premium"
    ]
)

// Clear user on logout
CanviqSDK.shared.reset()

Quick Start (Android)

Installation (Gradle)

implementation 'com.canviq:sdk-android:1.0.0'

Initialization

import com.canviq.sdk.CanviqSDK

CanviqSDK.initialize(
    context = applicationContext,
    apiKey = "your-api-key",
    userId = "user-123",
    locale = "en"
)

Show Survey

// Show immediately
CanviqSDK.showSurvey(surveyId = "survey-id")

// Show after user action
exportButton.setOnClickListener {
    CanviqSDK.showSurvey(
        surveyId = "survey-id",
        trigger = "export_clicked",
        metadata = mapOf("format" to "pdf")
    )
}

User Identification

// Identify user after login
CanviqSDK.identify(
    userId = "user-123",
    properties = mapOf(
        "email" to "user@example.com",
        "name" to "Jane Doe",
        "role" to "premium"
    )
)

// Clear user on logout
CanviqSDK.reset()

Detailed Platform Guides

For full integration guides, see:

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