JavaScript (Node.js)

Installation

npm install @rybbit/node

yarn add @rybbit/node

Initialization

Syntax

import { Rybbit } from "@rybbit/node";
 
const rybbit = new Rybbit(config: RybbitConfig);

Example

import { Rybbit } from "@rybbit/node";
 
const rybbit = new Rybbit({
  analyticsHost: "https://api.rybbit.io/api",
  siteId: "1",
  apiKey: "your-secret-api-key",
});

Configuration Options

Tracking Pageviews

While pageviews are traditionally a browser concept, the Node.js SDK provides a pageview method to track events that are analogous to a user viewing a page or a significant resource. This can be useful for tracking views of server-rendered pages before client-side JavaScript takes over, or for tracking views of API resources.

Syntax

await rybbit.pageview(payload?: Payload);

Parameters

• payload (object, Optional): An object containing details about the pageview. All properties are optional.
  • hostname (string): The hostname associated with this pageview.
  • pathname (string): The path of the page/resource being viewed.
  • querystring (string): Any query parameters associated with the path.
  • screenWidth (number): Screen width in pixels.
  • screenHeight (number): Screen height in pixels.
  • language (string): Language code.
  • page_title (string): The title of the page or resource.
  • referrer (string): The referrer URL.
  • user_id (string): A unique identifier for the user.
  • user_agent (string): The user agent string of the client.
  • ip_address (string): The IP address of the client.

Example

// Track a server-rendered page view
async function handleProductPageRequest(req, res) {
  // ... server logic to render product page ...
 
  await rybbit.pageview({
    hostname: req.hostname,
    pathname: `/products/${req.params.productId}`,
    page_title: `Product - ${product.name}`,
    ip_address: req.ip
  });
 
  // ... send response ...
}
 
// Track an API resource view
async function serveApiResource(req) {
  await rybbit.pageview({
    hostname: "api.myservice.com",
    pathname: `/v1/items/${req.params.itemId}`,
    user_id: req.user.id,
    ip_address: req.ip
  });
  // ... return API data ...
}

Tracking Custom Events

Use custom events to track specific actions or milestones occurring in your backend system. Examples include user account creation, background job completion, API endpoint usage, or any significant server-side process.

Syntax

await rybbit.event(eventName: string, payload?: Payload, properties?: TrackProperties);

Parameters

• eventName (string, Required): The name of the event you want to track.
• payload (object, Optional): An object containing contextual details for the event. All properties are optional.
  • hostname (string): The hostname associated with this event.
  • pathname (string): The path or resource context for this event.
  • querystring (string): Any query parameters relevant to the event’s context.
  • screenWidth (number): Screen width in pixels.
  • screenHeight (number): Screen height in pixels.
  • language (string): Language code.
  • page_title (string): The title of the page or resource context.
  • referrer (string): The referrer URL.
  • user_id (string): A unique identifier for the user.
  • user_agent (string): The user agent string of the client.
  • ip_address (string): The IP address of the client.
• properties (object, Optional): An object containing additional key-value pairs related to the event. Values can be a string, number, boolean, or an array of these types.

Example

// Track a new user registration
async function registerUser(userData, req) {
  // ... process user registration ...
 
  await rybbit.event("user_registered",
    {
      hostname: "auth.myservice.com",
      pathname: "/register",
      ip_address: req.ip
    },
    {
      userId: newUserId,
      registrationMethod: "email"
    }
  );
}
 
// Track a background job completion
async function processDailyReport(reportId) {
  // ... generate report ...
 
  await rybbit.event("report_generated",
    {},
    {
      reportId: reportId,
      status: "success",
      processingTimeMs: 12345
    }
  );
}
 
// Track an API endpoint usage with specific data
async function handleApiRequest(req) {
    // ... handle request ...
    await rybbit.event(
        "api_v1_item_lookup",
        {
          hostname: req.hostname,
          pathname: req.path,
          user_id: req.user.id,
          ip_address: req.ip
        },
        {
          itemId: req.params.itemId,
          clientVersion: req.headers["x-client-version"]
        }
    );
    // ... return response ...
}