@rakutenanalytics/rat-ts 0.6.2-rc.c84a2bd

package/README.md

@@ -0,0 +1,322 @@
+# 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.