CanDecide JS SDK

The CanDecide JS SDK allows developers to integrate the capabilities of the CanDecide platform into their JS applications seamlessly. This SDK provides functionalities to track user events, log data, manage user information, and handle session data efficiently with a focus on performance and simplicity.

Features

• Event Tracking: Track and buffer user events and send them in bulk to optimize network usage.
• Metric Tracking: Track and buffer metrics data to identify values over time in your Dashboard
• User Management: Upsert user data and manage user identifiers.
• Logging: Support for info, warn, error, and debug logs.
• Flexible Configuration: Configure project keys, environment, and other parameters.
• Automated Buffer Management: Events and logs are buffered and sent periodically to reduce network load.
• Error Handling: Robust error handling mechanisms to ensure stability.

Installation

Install the SDK using npm:

npm install @candecide/client

Or using yarn:

yarn add @candecide/client

Usage

Initializing the SDK

First, import and initialize the SDK with your project configuration:

import { CanDecideClient } from '@candecide/client';

const sdk = new CanDecideClient({
    projectKey: 'your-project-key',
    environmentKey: 'your-environment-key',
    sourceKey: 'your-source-key',
    logEnabled: true,
    trackingEnabled: true,
});

Setting User ID

To track user-specific data, set the user ID:

sdk.setUserId('unique-user-id');

Setting User Data

To track user specific properties

client.setUserData({
    userId: 'user-id',
    userProperties: {
        key: 'value',
    },
});

Enabling and Disabling Tracking and Logging

To enable or disable tracking, use the setTrackingEnabled method:

client.setTrackingEnabled(true); // Enable tracking
client.setTrackingEnabled(false); // Disable tracking

client.setLogsEnabled(true); // Enable logging
client.setLogsEnabled(false); // Disable logging

Setting User ID

To track user-specific data, set the user ID:

sdk.logPageView('https://example.com', {
    additional: 'parameters',
});

Tracking Events

Track an event with optional parameters:

sdk.trackEvent({
    event_name: 'purchase',
    event_parameters: { item: 'book', amount: 19.99 },
    user_id: 'unique-user-id' // This is optional if setUserId has been used
});

Tracking Metrics

Track a metric with a value and timestamp

sdk.trackMetric({
    metric_name: 'total_users',
    metric_value: 50000,
    metric_timestamp: '2021-09-01T12:00:00.000Z'
});

Creating Leads

Create leads directly from the sdk. Name is a required field. Everything else is optional.

sdk.createLead({
  name: "John Doe",
  email: "[email protected]",
  phone: "+1234567890",
  companyName: "Doe Industries",
  industry: "Manufacturing",
  jobTitle: "CEO",
  website: "https://doeindustries.com",
  country: "USA",
  city: "New York",
  state: "NY",
  address: "1234 Broadway Ave",
  postalCode: "10001",
  latitude: 40.7128,
  longitude: -74.0060,
  projectSourceId: "source123",
  projectLeadStatusId: "status123",
  value: 100000,
  ownerId: "owner123"
});

Logging

Log information, warnings, errors, or debug information:

sdk.logger.info('User logged in', { username: 'example_user' });
sdk.logger.warn('Usage limit nearing', { threshold: 90 });
sdk.logger.error('Payment failed', { error_code: 'PAY_001' });
sdk.logger.debug('Debugging data', { debug_info: 'Here' });

Flushing Data Manually

Force a flush of the event and log buffers:

await sdk.forceFlush();

Configuration Options

You can configure the SDK with the following options:

• projectKey (string): Your project key.
• environmentKey (string): The environment key (e.g., 'production', 'development').
• sourceKey (string): A unique identifier for the data source.
• logEnabled (boolean, optional): Enable or disable logging capabilities.
• trackingEnabled (boolean, optional): Enable or disable event tracking.
• baseUrl (string, optional): Base URL for the CanDecide ingestion API.

Best Practices

• Always handle potential exceptions when calling SDK methods, especially in production environments.

Support

For detailed documentation, visit our official documentation. For further assistance, contact our support team at [email protected].

License

This SDK is released under the MIT license. See the LICENSE file for more details.