Rakuten Analytics TypeScript SDK

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

Installation

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

Quick Start

Basic Usage

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

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

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.

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.

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).

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

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

Click Event

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

Conversion Event

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

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

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

ReceiverEndpoint

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

// 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

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

Content Visibility Tracking

// 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:

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

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.