Vai al contenuto
Capgo

Getting Started

Questo contenuto non è ancora disponibile nella tua lingua.

  1. Install the package

    Terminal window
    npm i @capgo/capacitor-appinsights

  2. Sync with native projects

    Terminal window
    npx cap sync

Usage

Import the plugin and initialize it with your AppInsights credentials:

import { CapacitorAppinsights } from '@capgo/capacitor-appinsights';


// Initialize the SDK
const initializeAnalytics = async () => {
  await CapacitorAppinsights.init({
    partnerId: 'your-partner-id',
    partnerKey: 'your-partner-key'
  });
};


// Set user ID for tracking
const setUser = async (userId: string) => {
  await CapacitorAppinsights.setUserId({ userId });
};


// Get SDK state
const checkSDKState = async () => {
  const state = await CapacitorAppinsights.getState();
  console.log('SDK State:', state);
};


// Get plugin version
const checkVersion = async () => {
  const { version } = await CapacitorAppinsights.getPluginVersion();
  console.log('Plugin version:', version);
};

API Reference

init(options)

Initialize the AppInsights SDK with your credentials.

await CapacitorAppinsights.init({
  partnerId: 'your-partner-id',
  partnerKey: 'your-partner-key'
});

Parameters:

  • partnerId (string): Your AppInsights partner ID
  • partnerKey (string): Your AppInsights partner key

setUserId(options)

Set or update the user ID after initialization.

await CapacitorAppinsights.setUserId({
  userId: 'user-123'
});

Parameters:

  • userId (string): The user ID to set for tracking

getState()

Get the current state of the SDK.

const state = await CapacitorAppinsights.getState();
console.log(state);
// {
//   initCompleted: true,
//   jobScheduled: true,
//   permissionAcquired: true
// }

Returns:

  • initCompleted (boolean): Whether SDK initialization is complete
  • jobScheduled (boolean): Whether data collection job is scheduled
  • permissionAcquired (boolean): Whether necessary permissions are acquired

getPluginVersion()

Get the native Capacitor plugin version.

const { version } = await CapacitorAppinsights.getPluginVersion();
console.log('Version:', version);

Complete Example

import { CapacitorAppinsights } from '@capgo/capacitor-appinsights';


export class AnalyticsService {
  private initialized = false;


  async initialize(partnerId: string, partnerKey: string) {
    try {
      await CapacitorAppinsights.init({
        partnerId,
        partnerKey
      });


      const state = await CapacitorAppinsights.getState();
      this.initialized = state.initCompleted;


      console.log('AppInsights initialized:', state);
    } catch (error) {
      console.error('Failed to initialize AppInsights:', error);
    }
  }


  async identifyUser(userId: string) {
    if (!this.initialized) {
      throw new Error('AppInsights not initialized');
    }


    await CapacitorAppinsights.setUserId({ userId });
    console.log('User identified:', userId);
  }


  async getSDKStatus() {
    const state = await CapacitorAppinsights.getState();
    return {
      ready: state.initCompleted && state.permissionAcquired,
      tracking: state.jobScheduled,
      state
    };
  }
}

Best Practices

  1. Initialize early Initialize the SDK as soon as your app starts to ensure accurate tracking:

    // In your app initialization
    await CapacitorAppinsights.init({
      partnerId: process.env.APPINSIGHTS_PARTNER_ID,
      partnerKey: process.env.APPINSIGHTS_PARTNER_KEY
    });

  2. Set user ID on login Identify users after authentication:

    async function onUserLogin(user) {
      await CapacitorAppinsights.setUserId({
        userId: user.id
      });
    }

  3. Check SDK state Verify SDK is ready before critical operations:

    const state = await CapacitorAppinsights.getState();
    if (!state.initCompleted) {
      console.warn('AppInsights not ready');
    }

  4. Handle errors gracefully

    try {
      await CapacitorAppinsights.init(config);
    } catch (error) {
      console.error('Analytics initialization failed:', error);
      // Continue app operation even if analytics fails
    }

Platform Notes

iOS

  • Requires iOS 10.0+
  • Ensure you have the necessary permissions in Info.plist for tracking

Android

  • Requires Android 5.0 (API 21)+
  • May require usage stats permission depending on tracking features

Web

  • Not supported on web platform