LogoStacked
Analytics SDK

Configuration

Complete configuration reference for the Analytics SDK

The Analytics SDK is highly configurable to fit various server-side integration scenarios. This page documents all available configuration options.

Configuration Interface

Prop

Type

Prop

Type

Required Options

apiKey

Required: Yes

Your API key from the dashboard. Used to authenticate all requests to the Stacked API.

const analytics = new PixelsAnalytics({
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: 'test'
});
config := pixels.Config{
    APIKey:   os.Getenv("PIXELS_API_KEY"),
    ClientID: os.Getenv("PIXELS_CLIENT_ID"),
    Env:      "test",
}

analytics, err := pixels.New(config)
if err != nil {
    log.Fatal(err)
}

Security Warning

Never hardcode API keys in your source code. Always use environment variables or secure secret management.

clientId

Required: Yes

Your client ID from the dashboard. Used alongside the API key for authentication.

const analytics = new PixelsAnalytics({
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: 'test'
});
config := pixels.Config{
    APIKey:   os.Getenv("PIXELS_API_KEY"),
    ClientID: os.Getenv("PIXELS_CLIENT_ID"),
    Env:      "test",
}

env

Required: Yes Options: 'test' | 'live' | 'staging' | 'dev'

The environment to connect to:

  • test (recommended for development) - https://api.sandbox.pixels.xyz
  • live (production) - https://api.pixels.xyz
  • staging (staging) - https://api.staging.pixels.xyz
  • dev (development) - https://api.dev.pixels.xyz
// Development
const analytics = new PixelsAnalytics({
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: 'test'
});

// Production
const analytics = new PixelsAnalytics({
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: 'live'
});
// Development
config := pixels.Config{
    APIKey:   os.Getenv("PIXELS_API_KEY"),
    ClientID: os.Getenv("PIXELS_CLIENT_ID"),
    Env:      "test",
}

// Production
config := pixels.Config{
    APIKey:   os.Getenv("PIXELS_API_KEY"),
    ClientID: os.Getenv("PIXELS_CLIENT_ID"),
    Env:      "live",
}

Environment Recommendation

Always use test environment during development and live for production.

Optional Batching Options

maxBatchSize

Default: 3000

Maximum number of events to batch before sending to the server. When this limit is reached, events are sent immediately regardless of the flush interval.

const analytics = new PixelsAnalytics({
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: 'test',
  maxBatchSize: 50 // Send when 50 events are queued
});
config := pixels.Config{
    APIKey:       os.Getenv("PIXELS_API_KEY"),
    ClientID:     os.Getenv("PIXELS_CLIENT_ID"),
    Env:          "test",
    MaxBatchSize: 50, // Send when 50 events are queued
}

Performance Tip

For high-traffic applications, increase maxBatchSize to reduce network overhead. For low-latency requirements, decrease it to send events more frequently.

flushInterval

Default: 5000 (5 seconds)

Time in milliseconds to wait before automatically flushing queued events. Events are sent either when this interval expires or when maxBatchSize is reached, whichever comes first.

const analytics = new PixelsAnalytics({
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: 'test',
  flushInterval: 10000 // Flush every 10 seconds
});
config := pixels.Config{
    APIKey:        os.Getenv("PIXELS_API_KEY"),
    ClientID:      os.Getenv("PIXELS_CLIENT_ID"),
    Env:           "test",
    FlushInterval: 10000, // Flush every 10 seconds (in milliseconds)
}

maxRetries

Default: 3

Maximum number of retry attempts for failed requests. Uses exponential backoff (2^n seconds) between retries.

const analytics = new PixelsAnalytics({
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: 'test',
  maxRetries: 5 // Retry up to 5 times
});

// Retry timeline with exponential backoff:
// 1st retry: after 1 second
// 2nd retry: after 2 seconds
// 3rd retry: after 4 seconds
// 4th retry: after 8 seconds
// 5th retry: after 16 seconds
config := pixels.Config{
    APIKey:     os.Getenv("PIXELS_API_KEY"),
    ClientID:   os.Getenv("PIXELS_CLIENT_ID"),
    Env:        "test",
    MaxRetries: 5, // Retry up to 5 times
}

// Retry timeline with exponential backoff:
// 1st retry: after 1 second
// 2nd retry: after 2 seconds
// 3rd retry: after 4 seconds
// 4th retry: after 8 seconds
// 5th retry: after 16 seconds

Production Warning

After reaching maxRetries, events will be dropped to prevent memory buildup. Monitor your logs for retry failures.

maxQueueSize

Default: 100000

Maximum number of events that can be queued in memory. When this limit is reached, new events will be silently dropped to prevent memory issues.

const analytics = new PixelsAnalytics({
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: 'test',
  maxQueueSize: 50000 // Limit queue to 50k events
});
config := pixels.Config{
    APIKey:       os.Getenv("PIXELS_API_KEY"),
    ClientID:     os.Getenv("PIXELS_CLIENT_ID"),
    Env:          "test",
    MaxQueueSize: 50000, // Limit queue to 50k events
}

Optional Debug Options

debug / enableLogging

Default: false

Enable debug logging to the console. Useful for development and troubleshooting.

const analytics = new PixelsAnalytics({
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: 'test',
  debug: true // Enable debug logs
});

When enabled, you'll see logs like:

[PixelsAnalytics] Batching event: sign_in
[PixelsAnalytics] Flushing 5 events...
[PixelsAnalytics] Events sent successfully
config := pixels.Config{
    APIKey:        os.Getenv("PIXELS_API_KEY"),
    ClientID:      os.Getenv("PIXELS_CLIENT_ID"),
    Env:           "test",
    EnableLogging: true, // Enable debug logs
}

When enabled, you'll see logs like:

Pixels SDK initialized with valid credentials! env: sandbox
Pixels SDK track endpoint: https://event-tracker.sandbox.data.pixels.xyz/api/track
Flushing 5 events...
Events sent successfully

Production Warning

Disable debug logging in production to avoid exposing internal state and improve performance.

Optional Advanced Options

jwtExpirySeconds

Default: 3600 (1 hour)

JWT token expiry time in seconds. Tokens generated via signJwt() will expire after this duration.

const analytics = new PixelsAnalytics({
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: 'test',
  jwtExpirySeconds: 900 // 15 minutes
});

// Generate JWT with custom expiry
const token = await analytics.signJwt({ playerId: 'player-123' });
jwtExpiry := int64(900) // 15 minutes
config := pixels.Config{
    APIKey:           os.Getenv("PIXELS_API_KEY"),
    ClientID:         os.Getenv("PIXELS_CLIENT_ID"),
    Env:              "test",
    JWTExpirySeconds: &jwtExpiry,
}

// Generate JWT with custom expiry
token, err := analytics.SignJwt(ctx, "player-123")

Security Balance

Shorter expiry times are more secure but require more frequent token refresh. Longer expiry times reduce server load but increase security risk if tokens are compromised.

disableTracking

Default: false

When true, prevents all events from being sent. Useful for testing or temporarily disabling analytics without removing SDK calls.

const analytics = new PixelsAnalytics({
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: 'test',
  disableTracking: process.env.DISABLE_ANALYTICS === 'true'
});

// Events will be ignored when disableTracking is true
analytics.signIn('player-123', { username: 'Test' });
config := pixels.Config{
    APIKey:          os.Getenv("PIXELS_API_KEY"),
    ClientID:        os.Getenv("PIXELS_CLIENT_ID"),
    Env:             "test",
    DisableTracking: os.Getenv("DISABLE_ANALYTICS") == "true",
}

// Events will be ignored when DisableTracking is true
analytics.SignIn(ctx, "player-123", pixels.SignInParams{
    Username: stringPtr("Test"),
})

Graceful Shutdown

Both SDKs automatically handle graceful shutdown, ensuring all queued events are flushed before the process exits.

// The SDK automatically flushes on SIGINT and SIGTERM
const analytics = new PixelsAnalytics({
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: 'test'
});

// Manual flush if needed
await analytics.flush();
analytics, err := pixels.New(config)
if err != nil {
    log.Fatal(err)
}

// Use defer to ensure graceful shutdown
defer analytics.Close()

// Manual flush if needed
err = analytics.Flush(ctx)

Best Practice

Always call close() / Close() or use defer analytics.Close() to ensure events are flushed before your application exits.

Complete Configuration Example

import PixelsAnalytics from '@pixels-online/pixels-analytics-node-sdk';

const analytics = new PixelsAnalytics({
  // Required
  apiKey: process.env.PIXELS_API_KEY!,
  clientId: process.env.PIXELS_CLIENT_ID!,
  env: process.env.NODE_ENV === 'production' ? 'live' : 'test',

  // Optional - Batching
  maxBatchSize: 3000,
  flushInterval: 5000,
  maxRetries: 3,
  maxQueueSize: 100000,

  // Optional - JWT
  jwtExpirySeconds: 3600,

  // Optional - Debug
  debug: process.env.NODE_ENV !== 'production',
  disableTracking: process.env.DISABLE_ANALYTICS === 'true'
});

export default analytics;
package main

import (
    "log"
    "os"

    pixels "github.com/pixels-online/pixels-analytics-go-sdk"
)

func main() {
    env := "test"
    if os.Getenv("ENV") == "production" {
        env = "live"
    }

    jwtExpiry := int64(3600)

    config := pixels.Config{
        // Required
        APIKey:   os.Getenv("PIXELS_API_KEY"),
        ClientID: os.Getenv("PIXELS_CLIENT_ID"),
        Env:      env,

        // Optional - Batching
        MaxBatchSize:  3000,
        FlushInterval: 5000, // milliseconds
        MaxRetries:    3,
        MaxQueueSize:  100000,

        // Optional - JWT
        JWTExpirySeconds: &jwtExpiry,

        // Optional - Debug
        EnableLogging:   env != "live",
        DisableTracking: os.Getenv("DISABLE_ANALYTICS") == "true",
    }

    analytics, err := pixels.New(config)
    if err != nil {
        log.Fatalf("Failed to create analytics client: %v", err)
    }
    defer analytics.Close()

    // Use analytics...
}

Getting Started

Complete tutorial for integrating the Analytics SDK into your server

Event Tracking

Track user events to build profiles and trigger targeted offers

On this page

Configuration InterfaceRequired OptionsapiKeyclientIdenvOptional Batching OptionsmaxBatchSizeflushIntervalmaxRetriesmaxQueueSizeOptional Debug Optionsdebug / enableLoggingOptional Advanced OptionsjwtExpirySecondsdisableTrackingGraceful ShutdownComplete Configuration Example