@specula/sdk
v1.0.12
Published
Specula Web SDK for event tracking.
Readme
Specula Web SDK
This guide explains how to integrate the Specula Web SDK into your web application or server-side applications to track events, leveraging its automatic context enrichment and robust device fingerprinting (for web environments).
1. Installation
First, add the Specula SDK package to your project using npm or yarn.
npm install @specula/sdkor
yarn add @specula/sdk2. Initialization
Initialize the SDK as early as possible in your application's lifecycle.
Note: Upon successful initialization, the SDK automatically triggers an init event. You do not need to track this event manually.
For Web Applications (Browser Environment)
Use specula.init() with your unique Tenant API Key. The SDK will automatically handle device fingerprinting and context collection.
A) Via NPM Package (for modern frontend frameworks like React, Vue, etc.)
// Example for a plain JavaScript application
import specula from '@specula/sdk';
specula.init({
apiKey: 'YOUR_TENANT_API_KEY', // Replace with your actual API key
debug: true, // Enable debug mode to see detailed logs in the console and use development API endpoints (disable in production)
stealth: true, // Set to true to prioritize pixel tracking (GET requests) over POST requests
});
// Track an initial page view
specula.track('page_view');
// Example for a React application (e.g., in App.js)
import React, { useEffect } from 'react';
import specula from '@specula/sdk';
function App() {
useEffect(() => {
specula.init({
apiKey: 'YOUR_TENANT_API_KEY', // Replace with your actual API key
debug: process.env.NODE_ENV === 'development', // Enable debug mode in development (disable in production)
stealth: true, // Set to true to prioritize pixel tracking (GET requests) over POST requests
});
specula.track('page_view');
}, []);
return (
<div className="App">
{/* Your application components */}
</div>
);
}
export default App;B) Via a Simple <script> Tag (for quick integration)
Include the SDK script in the <head> of your HTML file. The specula object will be globally available.
<!-- In the <head> of the HTML file -->
<script src="https://cdn.specula-ai.com/sdk/v1/specula.min.js"></script>
<script>
// Initialize with the unique API Key from the Specula Dashboard
specula.init({
apiKey: 'YOUR_TENANT_API_KEY', // Replace with your actual API key
debug: true, // Enable debug mode to see detailed logs in the console and use development API endpoints (disable in production)
stealth: true, // Set to true to prioritize pixel tracking (GET requests) over POST requests
});
// Track a page view
specula.track('page_view');
// Track a button click
document.getElementById('buy-button').addEventListener('click', () => {
specula.track('buy_button_clicked', { productId: 'prod-xyz', plan: 'premium' });
});
</script>For Server-Side Applications (API to API Tracking)
When using the SDK in a Node.js environment or for API-to-API tracking, set the isServer option to true. This will disable browser-specific context collection and device fingerprinting, allowing you to provide relevant context manually.
// Example for a Node.js backend
import specula from '@specula/sdk';
// Initialize for server-side use
specula.init({
apiKey: 'YOUR_TENANT_API_KEY', // Replace with your actual API key
isServer: true, // Crucial for server-side environments
debug: process.env.NODE_ENV === 'development', // Enable debug mode in development (disable in production) and use development API endpoints
});
// Example of tracking an event from the server
async function handleUserSignup(userId: string, userEmail: string) {
// You can generate or retrieve a sessionId and fingerprintId from your system
const sessionId = 'server-generated-session-123';
const fingerprintId = 'optional-server-fingerprint-abc'; // Optional for server-side
specula.track(
'user_signed_up',
{ userId, userEmail },
{ sessionId, fingerprintId } // Manually provide context
);
}
// Call your server-side tracking function
handleUserSignup('user-456', '[email protected]');3. Automatic Context Enrichment & Device Fingerprinting (Web Only)
For web applications, the Specula SDK automatically enriches every event with valuable context, ensuring comprehensive data collection without extra effort from your side. This includes:
- Device Fingerprinting (
fingerprintId): A stable, high-entropy identifier generated using advanced browser and device signals (e.g., Canvas, WebGL, user agent). This provides a more reliable way to identify anonymous users across sessions than traditional cookies. - Session ID (
sessionId): A unique identifier for the user's current session, automatically regenerated after a period of inactivity. - Page Information:
page_url(current page URL),page_referrer(the referring URL). - Browser & Device Details:
user_agent(browser's user agent string),screen_resolution(e.g., "1920x1080"),locale(browser's language setting).
These context properties are automatically included in the payload of every event sent to the Specula Tracking API.
4. Tracking Events
Once the SDK is initialized, you can import and use the specula.track() method in any part of your application to track user interactions. Provide an event name and an optional payload with custom data. For server-side tracking, you can also provide an optional context object to include sessionId, fingerprintId, or other custom context.
Example: Tracking a Button Click (Web)
// Example for a plain JavaScript application
document.getElementById('buy-button').addEventListener('click', () => {
specula.track('buy_button_clicked', { productId: 'prod-xyz', plan: 'premium' });
});
// Example for a React component
import React from 'react';
import specula from '@specula/sdk';
function PurchaseButton({ product }) {
const handlePurchase = () => {
specula.track('purchase_completed', {
productId: product.id,
price: product.price,
currency: 'USD',
});
// ... proceed with the purchase logic
};
return (
<button onClick={handlePurchase}>
Buy {product.name}
</button>
);
}
export default PurchaseButton;By following these steps, you can easily integrate Specula's powerful tracking, automatic context enrichment, and robust device fingerprinting capabilities into your web application, and also perform API-to-API tracking from your server-side applications.