Commencer

1. Installer the package

   npm

   npm i @capgo/capacitor-appinsights

   pnpm

   pnpm add @capgo/capacitor-appinsights

   yarn

   yarn add @capgo/capacitor-appinsights

   bun

   bun add @capgo/capacitor-appinsights

2. Synchroniser with Natif projects

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Utilisation

Importer the plugin and Initialiser 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 Référence

init(Options)

Initialiser 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 Mise à jour the Utilisateur ID after Initialisation.

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 Natif Capacitor plugin Version.

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

Terminé Exemple

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. Initialiser early Initialiser the SDK as soon as your Application 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 Utilisateur ID on Connexion Identify Utilisateurs after authentication:

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

3. Vérifier 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 Utilisation stats permission depending on tracking Fonctionnalités

Web

• Not supported on web platform