npm package: @rakutenanalytics/rat-ts
Description: A TypeScript SDK for Rakuten Analytics Tracking, providing type-safe analytics integration for web applications.
Latest version: 0.6.2

# Rakuten Analytics TypeScript SDK

A TypeScript SDK for Rakuten Analytics Tracking, providing type-safe analytics integration for web applications.

## Installation

```bash
# Install latest production version
npm install @rakutenanalytics/rat-ts
```

## Quick Start

### Basic Usage

```typescript
import { Tracker } from '@rakutenanalytics/rat-ts';

// Initialize tracker
const tracker = new Tracker({
  accountId: 999,
  serviceId: 1
});

// Track a page view
tracker.sendPageviewEvent({
  params: {
    pageName: 'home'
  }
});

// Track a click event
tracker.sendClickEvent({
  params: {
    itemId: ['product123', 'category456']
  }
});
```

### Advanced Configuration

```typescript
import { Tracker, TransportMethod, ReceiverEndpoint } from '@rakutenanalytics/rat-ts';

const tracker = new Tracker({
  accountId: 999,
  serviceId: 1,
  mainReceiver: ReceiverEndpoint.JP_SEC,
  transportMethod: TransportMethod.BEACON
});
```

## API Reference

### Tracker Class

#### Constructor Options

```typescript
interface TrackerOptions {
  accountId: number;                    // Required: Your Rakuten Analytics account ID
  serviceId: number;                    // Required: Your service ID
  mainReceiver?: ReceiverEndpoint;      // Optional: Analytics endpoint
  transportMethod?: TransportMethod;    // Optional: Data transport method
  customCookies?: Record<string, string>; // Optional: Custom cookie values
}
```

#### Methods

##### `sendPageviewEvent(params: PageviewParams): void`

Send a page view event.

```typescript
tracker.sendPageviewEvent({
  params?: InputGenericParams,         // Standard analytics parameters
  customParams?: CustomParams,         // Custom parameters for advanced use cases
  cvEvents?: ConversionEvents          // Conversion tracking events
});
```

##### `sendClickEvent(params: ClickEventParams): void`

Send a click event.

```typescript
tracker.sendClickEvent({
  params?: InputGenericParams,         // Standard analytics parameters
  customParams?: CustomParams,         // Custom parameters for advanced use cases
  cvEvents?: ConversionEvents          // Conversion tracking events
});
```

##### `sendEvent(event: Event): void`

Send a generic analytics event with the specified type and parameters (for advanced use cases).

```typescript
tracker.sendEvent({
  type: 'appear',                      // Event type: 'pv', 'click', 'appear', 'async', 'scroll'
  params?: InputGenericParams,         // Standard analytics parameters
  customParams?: CustomParams,         // Custom parameters for advanced use cases
  cvEvents?: ConversionEvents          // Conversion tracking events
});
```

### Event Types

#### Page View Event

```typescript
tracker.sendPageviewEvent({
  params: {
    pageName: 'product-detail',
    itemId: ['product123'],
    genre: ['electronics', 'smartphones']
  }
});
```

#### Click Event

```typescript
tracker.sendClickEvent({
  params: {
    itemId: ['product123', 'product456'],
    pageName: 'search-results'
  },
  customParams: {
    clktgt: 'product-image',
    totalresults: 150
  }
});
```

#### Conversion Event

```typescript
tracker.sendPageviewEvent({
  cvEvents: {
    'purchase_gms': 3400,        // Purchase amount
    'purchase_order': 1,         // Number of orders
    'purchase_shop': 2           // Number of shops
  }
});
```

#### Custom Event with Advanced Parameters

```typescript
tracker.sendEvent({
  type: 'async',
  params: {
    pageName: 'checkout',
    itemId: ['item1', 'item2'],
    genre: ['books', 'electronics'],
    price: [1200, 3400]
  },
  customParams: {
    hits: 5,
    rpgn: 2,
    sort: 1,
    notification: 3
  }
});
```

### Configuration Enums

#### TransportMethod

```typescript
enum TransportMethod {
  XHR = 'xhr',      // XMLHttpRequest (default)
  BEACON = 'beacon' // Navigator.sendBeacon (recommended for page unload)
}
```

#### ReceiverEndpoint

```typescript
enum ReceiverEndpoint {
  JP = "rat.rakuten.co.jp",
  JP_SEC = "secure.rat.rakuten.co.jp",
  FR = "rat.rakuten.fr",
  DE = "rat.rakuten.de",
  ES = "rat.rakuten.es",
  UK = "rat.rakuten.co.uk",
  STG_JP = "stg.rat.rakuten.co.jp",
  STG_JP_SEC = "stg.secure.rat.rakuten.co.jp",
  CHECK_JP = "check.rat.rakuten.co.jp",
  CHECK_JP_SEC = "check.secure.rat.rakuten.co.jp"
}
```

## Common Use Cases

### E-commerce Product Tracking

```typescript
// Product page view
tracker.sendPageviewEvent({
  params: {
    pageName: 'item',
    itemId: ['123456'],
    genre: ['electronics', 'smartphones'],
    price: [29800]
  }
});

// Add to cart click
tracker.sendClickEvent({
  params: {
    itemId: ['123456']
  },
  customParams: {
    clktgt: 'add-to-cart'
  }
});

// Purchase conversion
tracker.sendPageviewEvent({
  params: {
    pageName: 'purchase-complete'
  },
  cvEvents: {
    'purchase_gms': 29800,
    'purchase_order': 1,
    'purchase_item': 1
  }
});
```

### Search Results Tracking

```typescript
tracker.sendPageviewEvent({
  params: {
    pageName: 'search',
    searchQuery: 'smartphone iPhone'
  },
  customParams: {
    hits: 247,
    rpgn: 1,
    totalresults: 247,
    sort: 1
  }
});
```

### Content Visibility Tracking

```typescript
// Track when content becomes visible
tracker.sendEvent({
  type: 'appear',
  params: {
    page: 'article',
    itemid: ['article123']
  }
});

// Track scroll events
tracker.sendEvent({
  type: 'scroll',
  params: {
    page: 'article'
  },
  customParams: {
    scrollDepth: 75
  }
});
```

## TypeScript Integration

### Type Definitions

The SDK provides comprehensive TypeScript definitions for all parameters:

```typescript
import type { 
  TrackerOptions, 
  Event, 
  InputGenericParams, 
  ConversionEvents,
  CustomParams 
} from '@rakutenanalytics/rat-ts';

// Type-safe event creation
const pageviewParams: PageviewParams = {
  params: {
    pageName: 'home',
    itemId: ['123'],
    // TypeScript will provide autocomplete and validation
  }
};
```

### Enum Usage

```typescript
import { 
  PglEnum,
  PgtEnum,
  TransportMethod, 
  ReceiverEndpoint 
} from '@rakutenanalytics/rat-ts';

// Use enums for type safety
tracker.sendPageviewEvent({
  params: {
    pageLayout: PglEnum.PC,
    pageType: PgtEnum.TOP
  }
});
```

## Support

For questions, bug reports, or feature requests, please contact the Rakuten Analytics team.