npm package: @stochain/analytics-wrapper
Description: Analytics wrapper for Airbridge and custom tracking
Author: Stochain
Latest version: 1.0.0

# @stochain/analytics-wrapper

Analytics tracking wrapper for React Native with Airbridge SDK integration.

## Installation

```bash
npm install @stochain/analytics-wrapper
npm install airbridge-react-native-sdk
```

### iOS Setup

```bash
cd ios && pod install
```

Add to `ios/Podfile`:
```ruby
pod 'AirBridge', '~> 4.7.0'
```

### Android Setup

Add to `android/build.gradle`:
```gradle
allprojects {
  repositories {
    maven { url 'https://jitpack.io' }
  }
}
```

## Initialization

```typescript
import { Analytics } from '@stochain/analytics-wrapper';

// Initialize in App.tsx or index.js
Analytics.initialize('YOUR_AIRBRIDGE_APP_TOKEN');
```

## Features

- Wallet lifecycle tracking
- Transaction event monitoring
- User action analytics
- Custom event tracking
- Airbridge SDK integration
- TypeScript support

## Usage

### Wallet Events

```typescript
import { Analytics } from '@stochain/analytics-wrapper';

// Track wallet creation
Analytics.trackWalletCreate('internal'); // or 'metamask', 'walletconnect'

// Track wallet import
Analytics.trackWalletImport('mnemonic'); // or 'private_key'

// Track wallet connection
Analytics.trackWalletConnect('walletconnect');
```

### Transaction Events

```typescript
// Track swap transaction
Analytics.trackSwap({
  fromToken: 'BNB',
  toToken: 'USDT',
  amount: '1.5',
  dex: 'pancakeswap'
});

// Track transfer
Analytics.trackTransfer({
  token: 'BNB',
  amount: '0.5',
  recipient: '0x...'
});

// Track transaction success
Analytics.trackTransactionSuccess('0x...');

// Track transaction failure
Analytics.trackTransactionFail('0x...', 'Insufficient gas');
```

### User Actions

```typescript
// Track screen view
Analytics.trackScreenView('WalletScreen');

// Track button click
Analytics.trackButtonClick('send_button');

// Track feature usage
Analytics.trackFeatureUsage('dex_swap');
```

### Custom Events

```typescript
// Track custom event with properties
Analytics.trackEvent('custom_event', {
  category: 'engagement',
  label: 'feature_x',
  value: 100
});
```

## Event Types

### Predefined Events

| Event | Method | Description |
|-------|--------|-------------|
| wallet_link | trackWalletCreate | Wallet creation completed |
| wallet_import | trackWalletImport | Wallet import completed |
| wallet_connect | trackWalletConnect | External wallet connected |
| swap_execute | trackSwap | Token swap executed |
| transfer_send | trackTransfer | Token transfer sent |
| tx_success | trackTransactionSuccess | Transaction confirmed |
| tx_fail | trackTransactionFail | Transaction failed |
| screen_view | trackScreenView | Screen viewed |
| button_click | trackButtonClick | Button clicked |
| feature_use | trackFeatureUsage | Feature used |

## API Reference

### Analytics Class

Static methods for event tracking:

```typescript
class Analytics {
  static initialize(appToken: string): void;
  static trackWalletCreate(chainType?: string): void;
  static trackWalletImport(importType?: string): void;
  static trackWalletConnect(walletType?: string): void;
  static trackSwap(params: SwapParams): void;
  static trackTransfer(params: TransferParams): void;
  static trackTransactionSuccess(txHash: string): void;
  static trackTransactionFail(txHash: string, error?: string): void;
  static trackScreenView(screenName: string): void;
  static trackButtonClick(buttonName: string): void;
  static trackFeatureUsage(featureName: string): void;
  static trackEvent(eventName: string, properties?: object): void;
}
```

### TypeScript Types

```typescript
interface SwapParams {
  fromToken: string;
  toToken: string;
  amount: string;
  dex?: string;
}

interface TransferParams {
  token: string;
  amount: string;
  recipient: string;
}
```

## Best Practices

### Event Naming

Use consistent naming conventions:
```typescript
// Good
Analytics.trackEvent('wallet_create', { action: 'completed' });

// Avoid
Analytics.trackEvent('CreateWallet', { action: 'done' });
```

### Data Privacy

Never track sensitive information:
```typescript
// Bad - Don't do this
Analytics.trackEvent('wallet', { privateKey: '0x...' });

// Good
Analytics.trackEvent('wallet_create', { chainType: 'bsc' });
```

### Error Tracking

Track errors for debugging:
```typescript
try {
  await executeSwap();
  Analytics.trackTransactionSuccess(txHash);
} catch (error) {
  Analytics.trackTransactionFail(txHash, error.message);
}
```

## Advanced Usage

### User Identification

```typescript
import Airbridge from 'airbridge-react-native-sdk';

// Set user ID
Airbridge.setUserID('user_12345');

// Set user alias
Airbridge.setUserEmail('user@example.com');

// Set user attributes
Airbridge.setUserAttribute('plan', 'premium');
```

### Custom Properties

```typescript
// Add context to events
Analytics.trackEvent('purchase', {
  product_id: 'bnb_100',
  price: 100,
  currency: 'USD',
  payment_method: 'credit_card'
});
```

## Platform Support

- iOS 10.0+
- Android API 21+
- React Native 0.60.0+

## License

MIT

## Repository

https://github.com/stochain/packages