mobiqo-capacitor
Version:
Mobiqo SDK for Capacitor apps - Mobile analytics and user tracking
267 lines (266 loc) • 9.48 kB
TypeScript
import { MobiqoEvent } from "./MobiqoEvent";
export { MobiqoEvent } from "./MobiqoEvent";
/**
* Mobiqo app user data structure
*/
export interface AppUser {
/** Internal Mobiqo user ID */
id: string;
/** Project ID this user belongs to */
project_id: string;
/** RevenueCat user identifier */
revenue_cat_user_id?: string;
/** Mobiqo-generated username */
mobiqo_username: string;
/** User's operating system */
os: 'ios' | 'android';
/** Operating system version */
os_version: string;
/** Application version */
app_version: string;
/** User's country code */
country?: string;
/** User's language preference */
language?: string;
/** A/B testing group assignment */
group: 'red' | 'blue';
/** Timestamp when user was first seen */
first_seen_at: string;
/** Timestamp when user was last seen */
last_seen_at: string;
/** Currently active entitlements/subscriptions */
active_entitlements: string[];
}
export interface AdditionalData {
user_id?: string;
user_name?: string;
user_email?: string;
referrer?: string;
referrer_data?: Record<string, any>;
}
/**
* User analytics and prediction statistics
*/
export interface Statistics {
/** Purchasing power parity score */
purchasing_power_parity: number;
/** Predicted intent to make a purchase */
purchase_intent: number;
/** Average revenue per user */
avg_arpu: number;
/** Average revenue per paying user */
avg_arppu: number;
/** Average lifetime value */
avg_ltv: number;
}
/**
* Response from syncUser method
*/
export interface SyncUserResponse {
/** Whether this is a new user (first time syncing) */
isNewUser: boolean;
/** Complete user data */
appUser: AppUser;
/** User analytics and predictions */
statistics: Statistics;
}
/**
* Response from getUserInfo method
*/
export interface GetUserInfoResponse {
/** Complete user data */
appUser: AppUser;
/** User analytics and predictions */
statistics: Statistics;
}
/**
* Mobiqo Analytics Service for Capacitor apps
*
* This service provides analytics tracking, user management, and session handling
* for mobile applications using the Mobiqo platform.
*
* @example
* ```typescript
* import Mobiqo, { MobiqoEvent, SyncUserResponse, AppUser } from 'mobiqo-capacitor';
*
* const mobiqo = new Mobiqo();
* await mobiqo.init({ mobiqoKey: 'your-api-key' });
*
* // Sync user with optional additional data
* const result: SyncUserResponse = await mobiqo.syncUser({
* revenue_cat_user_id: 'user-123',
* include_advanced_analysis: true,
* additional_data: { user_id: 'user-123', user_name: 'John Doe', user_email: 'john.doe@example.com', referrer: 'google', referrer_data: { campaign_id: 'camp-456' } }
* });
* console.log('User OS:', result.appUser.os);
* console.log('Purchase intent:', result.statistics.purchase_intent);
*
* // Track events with optional additional data
* await mobiqo.trackEvent('button_clicked', MobiqoEvent.CLICK, { screen: 'home' });
* await mobiqo.trackEvent('screen_viewed', MobiqoEvent.SCREEN_VIEW);
* ```
*/
export default class Mobiqo {
private API_URL;
private heartbeatInterval;
/**
* Initialize the Mobiqo service with your API key
*
* This method must be called before using any other Mobiqo features.
* It validates your API key and stores the project ID for subsequent requests.
*
* @param options - Configuration options
* @param options.mobiqoKey - Your Mobiqo API key from the dashboard
* @returns Promise that resolves when initialization is complete
*
* @example
* ```typescript
* const mobiqo = new Mobiqo();
* await mobiqo.init({ mobiqoKey: 'your-mobiqo-api-key' });
* ```
*/
init({ mobiqoKey }: {
mobiqoKey: string;
}): Promise<void>;
/**
* Get device model information
*
* Returns actual device model when possible. For best results with Capacitor, install @capacitor/device:
* npm install @capacitor/device
*
* @returns Device model string or 'unknown' if not available
* @private
*/
private getDeviceModel;
/**
* Sync user data with Mobiqo and start a tracking session
*
* This method links a RevenueCat user ID with Mobiqo analytics and starts
* automatic heartbeat tracking (every 20 seconds). Call this after user login
* or when you want to start tracking a user's session.
*
* @param options - User sync options
* @param options.revenue_cat_user_id - The RevenueCat user identifier
* @param options.additional_data - Optional extra user data to store (email, plan, etc.)
* @returns Promise that resolves with user sync response including user data and statistics
*
* @example
* ```typescript
* // With additional data and advanced analysis
* await mobiqo.syncUser({
* revenue_cat_user_id: 'user-123',
* include_advanced_analysis: true,
* additional_data: {
* user_id: 'user-123',
* user_name: 'John Doe',
* user_email: 'john.doe@example.com',
* referrer: 'google',
* referrer_data: { campaign_id: 'camp-456' },
* }
* });
*
* // Without additional data and advanced analysis
* await mobiqo.syncUser({
* revenue_cat_user_id: 'user-123'
* });
* ```
*/
syncUser({ revenue_cat_user_id, include_advanced_analysis, additional_data }: {
revenue_cat_user_id: string;
include_advanced_analysis?: boolean;
additional_data?: AdditionalData;
}): Promise<SyncUserResponse | undefined>;
/**
* Update user data in Mobiqo
*
* This method allows you to update additional user data for an existing user.
* Use this when you want to update user information without creating a new session.
*
* @param options - User update options
* @param options.revenue_cat_user_id - The RevenueCat user identifier
* @param options.additional_data - Optional extra user data to update (email, name, etc.)
* @returns Promise that resolves when the update is complete
*
* @example
* ```typescript
* // Update user data
* await mobiqo.updateUser({
* revenue_cat_user_id: 'user-123',
* additional_data: {
* user_id: 'user-123',
* user_name: 'John Doe',
* user_email: 'john.doe@example.com',
* referrer: 'google',
* referrer_data: { campaign_id: 'camp-456' },
* }
* });
* ```
*/
updateUser({ revenue_cat_user_id, additional_data }: {
revenue_cat_user_id: string;
additional_data?: AdditionalData;
}): Promise<void>;
/**
* Retrieve user information from Mobiqo
*
* Fetches stored user data and analytics information for a specific user.
* Useful for displaying user stats or personalizing the app experience.
*
* @param options - User lookup options
* @param options.revenue_cat_user_id - The RevenueCat user identifier to look up
* @param options.include_advanced_analysis - Whether to include advanced analysis in the response (purchase probability and other data, but request takes more time)
* @returns Promise that resolves with user information including user data and statistics
*
* @example
* ```typescript
* const userInfo = await mobiqo.getUserInfo({
* revenue_cat_user_id: 'user-123',
* include_advanced_analysis: true
* });
* console.log('User OS:', userInfo.appUser.os);
* console.log('Purchase intent:', userInfo.statistics.purchase_intent);
* ```
*/
getUserInfo({ revenue_cat_user_id, include_advanced_analysis }: {
revenue_cat_user_id: string;
include_advanced_analysis?: boolean;
}): Promise<GetUserInfoResponse | undefined>;
/**
* Track a custom event with Mobiqo analytics
*
* Records user interactions, behaviors, and custom events for analytics.
* Events are automatically timestamped and associated with the current user session.
*
* @param event - Name/identifier for the event (e.g., 'button_clicked', 'screen_viewed')
* @param eventType - Type of event from MobiqoEvent enum (CLICK, SCREEN_VIEW, etc.)
* @param additionalData - Optional custom data to attach to the event
* @returns Promise that resolves with tracking confirmation
*
* @example
* ```typescript
* // Track a button click with additional data
* await mobiqo.trackEvent(
* 'subscribe_button_clicked',
* MobiqoEvent.CLICK,
* {
* button_location: 'home_screen',
* user_plan: 'free'
* }
* );
*
* // Track a screen view without additional data
* await mobiqo.trackEvent('settings_screen', MobiqoEvent.SCREEN_VIEW);
* ```
*/
trackEvent(event: string, eventType: MobiqoEvent, additionalData?: Record<string, any>): Promise<any>;
/**
* Send a heartbeat to maintain the user session
*
* Heartbeats are automatically sent every 20 seconds after syncUser() is called.
* This helps track active session duration and is handled internally by the SDK.
*
* @returns Promise that resolves with heartbeat confirmation
* @private
*/
private sendHeartbeat;
}