mobiqo-capacitor/README.md

Mobiqo SDK for Capacitor apps - Mobile analytics and user tracking

# Mobiqo Capacitor SDK

**⚠️ THIS PLUGIN HAS TO BE USED ALONG WITH THE ANALYTICS SERVICE MOBIQO ⚠️**

**👉 CREATE AN ACCOUNT HERE: https://getmobiqo.com?utm_source=npm**

---

A Capacitor plugin for integrating Mobiqo analytics into your mobile applications.

## Installation

```bash
npm install mobiqo-capacitor
```

## Usage

### Import the SDK

```typescript
import Mobiqo from 'mobiqo-capacitor';
import { MobiqoEvent } from 'mobiqo-capacitor';
```

### Initialize the plugin

```typescript
const mobiqo = new Mobiqo();

// Initialize with your Mobiqo API key
await mobiqo.init({ mobiqoKey: 'your-mobiqo-api-key' });
```

### Sync user data

```typescript
// With additional data (optional)
await mobiqo.syncUser({
  revenue_cat_user_id: 'user-123',
  additional_data: {
    email: 'user@example.com',
    plan: 'premium'
  }
});

// Without additional data
await mobiqo.syncUser({
  revenue_cat_user_id: 'user-123'
});
```

### Track events

```typescript
// Track an event with additional data (optional)
await mobiqo.trackEvent(
  'button_clicked',
  MobiqoEvent.CLICK,
  {
    button_name: 'subscribe',
    screen: 'home'
  }
);

// Track an event without additional data
await mobiqo.trackEvent('screen_opened', MobiqoEvent.SCREEN_VIEW);
```

### Get user information

```typescript
const userInfo = await mobiqo.getUserInfo({
  revenue_cat_user_id: 'user-123'
});
```

### Automatic Session Tracking

The SDK automatically sends heartbeats every 30 seconds after user sync to maintain session tracking. No manual intervention is required.

## API Reference

### Methods

#### `init(options)`
Initialize the Mobiqo service with your API key.
- `options.mobiqoKey` (string): Your Mobiqo API key

#### `syncUser(options)`
Sync user data with Mobiqo and start a session.
- `options.revenue_cat_user_id` (string): RevenueCat user ID
- `options.additional_data` (Record<string, any>, optional): Additional user data

#### `getUserInfo(options)`
Retrieve user information from Mobiqo.
- `options.revenue_cat_user_id` (string): RevenueCat user ID

#### `trackEvent(event, eventType, additionalData?)`
Track custom events.
- `event` (string): Event name
- `eventType` (MobiqoEvent): Event type from the MobiqoEvent enum
- `additionalData` (Record<string, any>, optional): Additional event data

### Event Types

```typescript
enum MobiqoEvent {
  CLICK = 'click',
  ACTION = 'action',
  SCREEN_VIEW = 'screen_view',
  PAYWALL_VIEW = 'paywall_view',
  PAYWALL_DISMISS = 'paywall_dismiss',
  PURCHASE_ATTEMPT = 'purchase_attempt',
  PURCHASE_SUCCESS = 'purchase_success',
  FORM_SUBMIT = 'form_submit',
  NAVIGATION = 'navigation',
  ERROR = 'error',
  CUSTOM = 'custom'
}
```

### Response Interfaces

#### `SyncUserResponse`
```typescript
interface SyncUserResponse {
  isNewUser: boolean;
  appUser: AppUser;
  statistics: Statistics;
}
```

#### `GetUserInfoResponse`
```typescript
interface GetUserInfoResponse {
  appUser: AppUser;
  statistics: Statistics;
}
```

#### `AppUser`
```typescript
interface AppUser {
  id: string;
  project_id: string;
  revenue_cat_user_id?: string;
  mobiqo_username: string;
  os: 'ios' | 'android';
  os_version: string;
  app_version: string;
  country?: string;
  language?: string;
  first_seen_at: string;
  last_seen_at: string;
  active_entitlements: string[];
}
```

#### `Statistics`
```typescript
interface Statistics {
  purchasing_power_parity: number;
  purchase_probability: number;
  avg_arpu: number;
  avg_arppu: number;
  avg_ltv: number;
}
```

## Requirements

- Capacitor 3.0+
- TypeScript 4.0+

## License

MIT

## Support

For support and questions, please contact the Mobiqo team.