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',
  include_advanced_analysis: false,
  additional_data: {
    user_id: 'user-123',
    user_name: 'John Doe',
    user_email: 'user@example.com',
    referrer: 'google',
    referrer_data: { campaign_id: 'camp-456', utm_source: 'newsletter' }
  }
});

// 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);
```

### Update user data

```typescript
// Update user information without creating a new session
await mobiqo.updateUser({
  revenue_cat_user_id: 'user-123',
  additional_data: {
    user_id: 'user-123',
    user_name: 'John Doe Updated',
    user_email: 'newemail@example.com',
    referrer: 'facebook',
    referrer_data: { campaign_id: 'camp-789' }
  }
});
```

### Get user information

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

### Automatic Session Tracking

The SDK automatically sends heartbeats every 20 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.include_advanced_analysis` (boolean, optional): whether or not to include advanced analysis in the response (to get the purchase probability and other data, but the request will take more time)
- `options.additional_data` (AdditionalData, optional): Additional user data (user_id, user_name, user_email, referrer, referrer_data)

#### `updateUser(options)`
Update user information without creating a new session.
- `options.revenue_cat_user_id` (string): RevenueCat user ID
- `options.additional_data` (AdditionalData, optional): Additional user data to update (user_id, user_name, user_email, referrer, referrer_data)

#### `getUserInfo(options)`
Retrieve user information from Mobiqo.
- `options.revenue_cat_user_id` (string): RevenueCat user ID
- `options.include_advanced_analysis` (boolean): whether or not to include advanced analysis in the response (to get the purchase probability and other data, but the request will take more time)

#### `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',
  PURCHASE_FAILED = 'purchase_failed',
  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_intent: number;
  avg_arpu: number;
  avg_arppu: number;
  avg_ltv: number;
}
```

#### `AdditionalData`
```typescript
interface AdditionalData {
  user_id?: string;
  user_name?: string;
  user_email?: string;
  referrer?: string;
  referrer_data?: Record<string, any>;
}
```

## Requirements

- Capacitor 3.0+
- TypeScript 4.0+

## License

MIT

## Support

For support and questions, please contact the Mobiqo team.