Ionic / Capacitor

npm install @swake/ionic
# or
yarn add @swake/ionic
# or
pnpm add @swake/ionic

npm install @capacitor/core @capacitor/device @capacitor/network \
  @capacitor/preferences @capacitor/app

# Sync native projects
npx cap sync

npm install @capacitor/filesystem @capacitor/camera

import { useEffect, useState } from 'react';
import { setupIonicReact, IonApp } from '@ionic/react';
import Swake from '@swake/ionic';

setupIonicReact();

function App() {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    const setup = async () => {
      await Swake.init({
        apiKey: 'ep_live_your_api_key',
        appVersion: '1.0.0',
        trigger: { position: 'bottom-right' },
      });
      setReady(true);
    };
    void setup();

    return () => { Swake.destroy(); };
  }, []);

  if (!ready) return null;

  return <IonApp>{/* your routes */}</IonApp>;
}

import { Component, OnInit, OnDestroy } from '@angular/core';
import Swake from '@swake/ionic';

@Component({ selector: 'app-root', templateUrl: 'app.component.html' })
export class AppComponent implements OnInit, OnDestroy {
  async ngOnInit() {
    await Swake.init({
      apiKey: 'ep_live_your_api_key',
      appVersion: '1.0.0',
      trigger: { position: 'bottom-right' },
    });
  }

  ngOnDestroy() {
    Swake.destroy();
  }
}

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue';
import Swake from '@swake/ionic';

onMounted(async () => {
  await Swake.init({
    apiKey: 'ep_live_your_api_key',
    appVersion: '1.0.0',
    trigger: { position: 'bottom-right' },
  });
});

onUnmounted(() => {
  Swake.destroy();
});
</script>

await Swake.init({
  apiKey: 'ep_live_your_api_key',        // required
  baseUrl: 'https://api.swake.io',       // optional — override for self-hosted or a proxy
  debug: false,                          // verbose console logs
  appVersion: '1.0.0',                   // shown per submission in portal
  autoCapture: {
    browserInfo: true,                   // attach device/browser info
  },
  surveys: {
    enabled: true,                       // fetch & show eligible surveys
    autoShow: true,                      // auto-show after identify()
    delay: 3000,                         // ms before auto-show
    cooldown: 86_400_000,                // ms between surveys (default: 24h)
  },
  breadcrumbs: {
    enabled: true,                       // attach breadcrumb trail
    maxEntries: 50,                      // ring buffer size (max 100)
    captureNavigation: true,             // route changes
    captureNetwork: true,                // fetch/XHR calls
    captureConsole: true,                // console.warn/error
    captureClicks: true,                 // element click events
  },
  trigger: {
    position: 'bottom-right',            // FAB position
    icon: 'chat',                        // 'feedback' | 'bug' | 'idea'
    label: 'Feedback',
    hidden: false,
    zIndex: 999999,
    style: {
      backgroundColor: '#059669',
      size: 56,
      borderRadius: 28,
      shadow: true,
    },
  },
  theme: { /* see Theme Customization section */ },
  onLimitReachedMode: 'default_ui',      // 'silent' | 'callback_only'
  onLimitReached: (event) => {
    console.warn(event.limitKey, event.message);
  },
});

import Swake from '@swake/ionic';

await Swake.identify({
  userId: 'user_123',         // required — your app's user ID
  email: 'jane@example.com',  // optional
  name: 'Jane Smith',         // optional
  metadata: {                 // optional — arbitrary key-value pairs
    plan: 'pro',
    company: 'Acme Corp',
  },
});

Swake.clearIdentity();

import Swake from '@swake/ionic';

// Default form
Swake.showFeedbackForm();

// With options
Swake.showFeedbackForm({
  defaultType: 'feature',           // pre-select type
  showTypeSelector: true,           // show/hide type toggle (default: true)
  title: "What's on your mind?",    // header text
  placeholder: 'Tell us more...',   // textarea placeholder
  theme: { primaryColor: '#8B5CF6' }, // per-call theme override
});

import { IonButton, IonIcon } from '@ionic/react';
import { chatbubbleOutline } from 'ionicons/icons';
import Swake from '@swake/ionic';

function FeedbackButton() {
  return (
    <IonButton onClick={() => Swake.showFeedbackForm({ defaultType: 'bug' })}>
      <IonIcon slot="start" icon={chatbubbleOutline} />
      Report a Bug
    </IonButton>
  );
}

// In your init config, hide the trigger:
// trigger: { hidden: true }

import Swake, { nativeFileToFile } from '@swake/ionic';
import { Camera, CameraResultType } from '@capacitor/camera';

// Take a photo
const photo = await Camera.getPhoto({
  resultType: CameraResultType.Uri,
  quality: 80,
});

// Convert the native URI to a File object
const file = await nativeFileToFile(photo.webPath ?? photo.path!);

// Submit with the attachment
await Swake.submitFeedback({
  type: 'bug',
  title: 'Screenshot attached',
  attachments: [{ file }],
});

import Swake from '@swake/ionic';

const submission = await Swake.submitFeedback({
  type: 'bug',                                      // 'bug' | 'feature' | 'question'
  title: 'App crashes on photo upload',              // required
  description: 'Reproducible on iPhone 15 Pro.',     // optional
  attachments: [                                      // optional — File objects
    { file: screenshotFile },
  ],
});

console.log('Created:', submission.id);

// Open the feedback history panel
Swake.showFeedbackHistory();

// Lightweight list (id, title, status, type, createdAt)
const { submissions, hasMore, cursor } = await Swake.getHistory({ limit: 20 });

// Full submission detail with comments + attachments
const submission = await Swake.getSubmission('submission_id');

// Paginated submission list with more fields
const result = await Swake.listSubmissions({ limit: 10 });

await Swake.init({
  apiKey: 'ep_live_...',
  trigger: {
    position: 'bottom-right',     // 'bottom-left' | 'top-right' | 'top-left'
    icon: 'chat',                 // 'feedback' | 'bug' | 'idea'
    label: 'Feedback',
    hidden: false,
    zIndex: 999999,
    style: {
      backgroundColor: '#059669',
      size: 56,                   // diameter in px
      borderRadius: 28,
      shadow: true,
    },
  },
});

// Hide the FAB (e.g. during onboarding)
Swake.setTriggerVisible(false);

// Show it again
Swake.setTriggerVisible(true);

// Programmatic open / close
Swake.open();    // opens the feedback form
Swake.close();   // closes any open widget

// Configure at init
await Swake.init({
  apiKey: 'ep_live_...',
  surveys: {
    enabled: true,        // default: true
    autoShow: true,       // auto-show after identify()
    delay: 3000,          // ms before auto-show
    cooldown: 86_400_000, // ms between surveys (default: 24h)
  },
});

// Manual control
await Swake.checkSurveys();              // re-check eligibility
await Swake.showSurvey('survey_abc123'); // show specific survey (ignores cooldown)

Swake.onSurveyShown((event) => {
  console.log('Survey shown:', event.id, event.type);
});

Swake.onSurveyCompleted((event) => {
  console.log('Completed:', event.survey.id, 'answers:', event.response.answers);
});

Swake.onSurveyDismissed((event) => {
  console.log('Dismissed:', event.id);
});

// Fetch board items
const { items, hasMore } = await Swake.getBoardItems('public-roadmap', {
  sort: 'votes',      // 'votes' | 'recent'
  status: 'open',     // 'open' | 'in_progress' | 'resolved' | 'closed'
  page: 1,
});

// Cast a vote (requires identify)
const { status, voteCount } = await Swake.vote('public-roadmap', 'item_id');

// Remove a vote
const result = await Swake.removeVote('public-roadmap', 'item_id');

// Get unread count
const count = await Swake.getUnreadCount();

// List notifications
const { notifications, pagination } = await Swake.listNotifications({
  unreadOnly: true,
  limit: 20,
  cursor: undefined,
});

// Mark as read
await Swake.markNotificationRead('notification_id');

// Mark all as read
await Swake.markAllNotificationsRead();

await Swake.init({
  apiKey: 'ep_live_your_api_key',
  theme: {
    primaryColor: '#059669',       // buttons, active states, FAB
    successColor: '#10B981',       // success states
    dangerColor: '#EF4444',        // error states
    backgroundColor: '#FFFFFF',    // panel backgrounds
    surfaceColor: '#F8FAFC',       // cards, input backgrounds
    overlayColor: 'rgba(15,23,42,0.4)', // backdrop
    textColor: '#0F172A',          // primary text
    textSecondary: '#64748B',      // muted text
    borderColor: '#E2E8F0',        // borders, dividers
    borderRadius: 10,              // px
    fontFamily: 'Inter, sans-serif',
  },
});

Swake.showFeedbackForm({
  theme: { primaryColor: '#0EA5E9' },
});

Swake.addBreadcrumb({
  category: 'custom',
  message: 'User completed onboarding',
  data: { step: 'final', durationMs: 4500 },
});

// Read the current trail
const trail = Swake.getBreadcrumbs();

// Clear the buffer
Swake.clearBreadcrumbs();

import { offlineQueue } from '@swake/ionic';

// Check queue size (e.g. show a badge)
const pending = offlineQueue.size();

// Force a flush attempt
await offlineQueue.flush();

Fully integrate the Swake feedback SDK (feedback forms, bug reports, surveys/NPS, in-app notifications, voting boards) into this Ionic + Capacitor app. Treat it as additive: a Swake or network failure must NEVER break boot or any existing behavior. Never invent or fake an API that is not in the docs.

1. READ THE DOCS FIRST — they are the source of truth for the package, the Capacitor peers, init/identify and native setup. Fetch with a browser User-Agent (a plain fetch returns 403): curl -sL -A "Mozilla/5.0" "https://swake.io/docs/sdk?framework=ionic". Then detect the Capacitor major version and which UI framework Ionic is running (React, Angular, or Vue) and say which you found; if there is no Capacitor here, STOP and use the matching web guide instead.
2. ASK BEFORE DECIDING ANYTHING (AskUserQuestion): (a) the API key (ep_live_...), an optional baseUrl, and a voting-board slug if they want the board — written as PLACEHOLDERS ONLY into env files and the .example alongside, never a real key; (b) confirmation to install the required Capacitor peers @capacitor/core, @capacitor/app, @capacitor/device, @capacitor/network and @capacitor/preferences, plus @capacitor/filesystem only if they want native file attachments and @capacitor/camera only if they want in-app photo capture. Install nothing that was not approved, then run npx cap sync.
3. INSTALL — add @swake/ionic, NOT @swake/web. It wraps the full web SDK and adds native adapters for storage, device info and network events. The widget layer is already imported for you, so do NOT add an '@swake/web/ui' import — doing so is redundant.
4. INIT EXACTLY ONCE AND AWAIT IT — Swake.init() is ASYNC in this package (unlike @swake/web) because it preloads the Capacitor adapters before the underlying web SDK starts; a missing await means later calls run against an uninitialised SDK. Keep a module-level "let initPromise: Promise<void> | null" and have every caller await the SAME promise: the SDK exposes no isInitialized(), every method throws "[Swake] SDK not initialized" before init(), and a second init() starts a second offline-queue flush interval without clearing the first. Call it from AppComponent.ngOnInit (Angular), a root useEffect (React), or onMounted in App.vue (Vue), and Swake.destroy() on teardown. Set trigger: { hidden: true } if the app will open feedback from its own Ionic button.
5. IDENTITY — after init resolves, call Swake.identify({ userId, email, name, metadata }) on EVERY launch that has a session, not just on the login event: identity is held in memory only, so an app restart loses it. userId must be your stable internal id, and every metadata value must be a string. On logout call Swake.clearIdentity() inside a try/catch — it throws if init never ran.
6. NATIVE & POLISH — for attachments use nativeFileToFile(uri) from @swake/ionic to turn a Camera or Filesystem URI into a File, then pass it as attachments: [{ file }]. Add the iOS Info.plist usage strings for camera and photo library only for the plugins you actually installed. Drive Swake.setTheme() from the app's light/dark toggle, and gate init/identify by route so an auto-shown survey never lands on onboarding or auth pages.
7. VERIFY & REPORT — funnel every SDK call through one wrapper with try/catch. Then verify on a real iOS AND Android build, not just the browser: a real submission with an attachment appears in the Swake dashboard, queued feedback flushes after the device goes offline and back online, and no survey shows during onboarding. Note that every Capacitor adapter fails soft to its browser default, so a missing plugin degrades quietly rather than throwing — check the dashboard shows real native device info, which is the visible proof the adapters are actually wired. Report files changed, manual steps left, and assumptions made.