@cross-classify/xc-sdk

v1.2.14

Published

2 months ago

CrossClassify Package

0High
0Medium
0Low

kyle-evans1041

harry-bavar

security form-tracking analytics cdn

xc-sdk

CrossClassify Package for advanced form tracking and analytics with seamless integration across web frameworks.

🚀 Features

Cross-framework support: Works with Angular (2+), AngularJS (1.x), React, and vanilla JavaScript
Automatic form detection: Intelligently detects login and signup forms
Custom element targeting: Override default selectors for specific elements
Real-time interaction tracking: Monitors user interactions with form elements
Fingerprinting integration: Uses FingerprintJS for visitor identification
Developer-friendly: Built-in developer mode with detailed logging

📦 Installation

NPM/Yarn

npm install @cross-classify/xc-sdk
# or
yarn add @cross-classify/xc-sdk

CDN

For quick integration without package managers, include the CrossClassify SDK directly via CDN. This approach works well for static websites or when you want to add tracking to existing forms without modifying your build process. The loginRoute and signupRoute parameters should match the URL paths where your login and signup forms are hosted in your application (at least one is required).

<body>
  //other scripts...
  <script src="https://unpkg.com/@cross-classify/xc-sdk@latest/dist/xc-sdk.min.js"></script>
  <script>
    CrossClassify.initXC(SITE_ID, API_KEY, {
      developerMode: true,
      loginRoute: LOGIN_ROUTE, // eg: "/auth/login"
      signupRoute: SIGNUP_ROUTE, // eg: "/auth/signup"
    });
  </script>
</body>

❓ How does this work?

When you include XC SDK via CDN, the script automatically runs in the browser and starts looking for login/signup forms. It does this using a heuristic-based element detection system:

Scans the page for elements that look like email inputs (required)
Detects password fields by type or naming patterns (optional)
Identifies submit buttons by attributes or text content (e.g., "Login", "Sign in") (required)

Note: Password field is optional. The SDK will work with just email and submit button elements if no password field is present.

If your form uses standard HTML inputs, most of the time it will be tracked automatically without any extra configuration.

Behind the scenes, the SDK uses a combination of:

CSS selectors (input[type="email"], button[type="submit"], etc.)
Attribute matching (name*="user", id*="pass", etc.)
Text-based matching (button text like "Login", "Submit", "Register")

This means it can work out-of-the-box on most login/signup pages.

If your app uses non-standard form markup, you can override this by providing your own formElementSelectors in the config.

👉 check the Troubleshooting section.

🔧 Framework Integration

React

1. Install the package:

npm install @cross-classify/xc-sdk

2. Initialize CrossClassify in your root component

import React, {useEffect} from "react";
import {initXC} from "@cross-classify/xc-sdk";

const App = () => {
  useEffect(() => {
    initXC(SITE_ID, API_KEY, {
      developerMode: true,
      loginRoute: LOGIN_ROUTE, // eg: "/auth/login"
      signupRoute: SIGNUP_ROUTE, // eg: "/auth/signup"
    });
  }, []);

  return (
    ...
  );
};

Angular

1. Install the package:

npm install @cross-classify/xc-sdk

2. Initialize CrossClassify in your root component

import {Component, OnInit} from "@angular/core";
import {initXC} from "@cross-classify/xc-sdk";

@Component({
  selector: "app-root",
  template: `...`,
})
export class AppComponent implements OnInit {
  ngOnInit() {
    initXC(SITE_ID, API_KEY, {
      developerMode: true,
      loginRoute: LOGIN_ROUTE, // eg: "/auth/login"
      signupRoute: SIGNUP_ROUTE, // eg: "/auth/signup"
    });
  }
}

AngularJS (1.x)

For a complete guide including hash-mode routing, HTML5 mode, and troubleshooting, see docs/angularjs-integration.md.

1. Install the package:

npm install @cross-classify/xc-sdk

Or use the CDN (more common for AngularJS 1.x apps):

<script src="https://unpkg.com/@cross-classify/xc-sdk@latest/dist/xc-sdk.min.js"></script>

2. Initialize CrossClassify in your app's .run() block

// CDN usage
angular.module("myApp", []).run(function () {
  CrossClassify.initXC(SITE_ID, API_KEY, {
    developerMode: true,
    loginRoute: LOGIN_ROUTE, // eg: "/login"
    signupRoute: SIGNUP_ROUTE, // eg: "/signup"
  });
});

// npm / bundled usage
import {initXC} from "@cross-classify/xc-sdk";

angular.module("myApp", []).run(function () {
  initXC(SITE_ID, API_KEY, {
    developerMode: true,
    loginRoute: LOGIN_ROUTE, // eg: "/login"
    signupRoute: SIGNUP_ROUTE, // eg: "/signup"
  });
});

Hash-mode routing: AngularJS uses #!/login-style URLs by default. The SDK automatically normalises these — configure routes using the plain path (e.g. "/login"), not the hash form.

⚙️ Configuration Options

The third parameter of initXC() accepts a configuration object with the following options:

Basic Configuration

The minimum configuration requires specifying at least one route where your forms are located. The SDK will monitor these routes and automatically detect form interactions when users navigate to them.

{
  // Enable detailed logging, debugging information, and visual overlay
  developerMode: true, // boolean, default: false

  // At least one route is required - specify where your forms are hosted
  loginRoute: "/auth/login",      // Your application's login page route
  signupRoute: "/auth/signup",    // Your application's signup page route
}

Advanced Element Selection

{
  // Custom selectors for form elements
  formElementSelectors: {
    // Email field selector (required)
    emailElementSelector: EMAIL_SELECTOR,       // eg: "#email-input"
    // or use CSS selectors
    emailElementSelector: 'input[name="email"]',
    // or use text search
    emailElementSelector: 'text:Email Address',

    // Password field selector (optional)
    passwordElementSelector: PASSWORD_SELECTOR,  // eg: "#password-input"
    passwordElementSelector: 'input[type="password"]',
    passwordElementSelector: 'text:Password',

    // Submit button selector (required)
    submitElementSelector: SUBMIT_SELECTOR,      // eg: "#submit-button"
    submitElementSelector: 'button[type="submit"]',
    submitElementSelector: 'text:Sign In'
  }
}

Note: Only email and submit button elements are required. The password field is optional and can be omitted for forms without password fields.

Complete Configuration Example

initXC(SITE_ID, API_KEY, {
  developerMode: true,
  loginRoute: LOGIN_ROUTE, // eg: "/auth/login" or "https://app.example.com/auth/login"
  signupRoute: SIGNUP_ROUTE, // eg: "/auth/register" or "https://app.example.com/auth/register"
  formElementSelectors: {
    emailElementSelector: EMAIL_SELECTOR, // eg: "#user-email"
    passwordElementSelector: PASSWORD_SELECTOR, // eg: "#user-password"
    submitElementSelector: SUBMIT_SELECTOR, // eg: "#login-submit"
  },
});

🎯 Element Selection Methods

The package supports multiple ways to identify form elements (Id selector, attribute selector and text selector):

1. CSS and Id Selectors (Recommended)

formElementSelectors: {
  emailElementSelector: '#email-element-id',         // ID selector
  passwordElementSelector: 'input[type="password"]', // Attribute selector
  submitElementSelector: 'input[type="submit"]' //Submit button selector
}

2. Text Content Search

formElementSelectors: {
  emailElementSelector: 'text:Email',         // Finds elements containing "Email"
  passwordElementSelector: 'text:Password',   // Finds elements containing "Password"
  submitElementSelector: 'text:Sign In'       // Finds buttons with "Sign In" text
}

3. Fallback to Auto-Detection

If you don't specify formElementSelectors, the package will automatically detect common form elements using built-in selectors.

🎯 Visual Element Detection Overlay

A visual debugging tool that highlights detected form elements with color-coded indicators and shows route matching status.

initXC(SITE_ID, API_KEY, {
  developerMode: true, // Enable visual debugging overlay
  loginRoute: "/auth/login",
});

Element Detection:

🟢 Green: Element found and tracked
🔴 Red: Element not found - needs custom selector

Route Matching:

🟢 Green with glow: Route matched - form tracking is active
🟠 Orange: Route not matched - form tracking is inactive

Additional Features:

Shows current route vs configured routes
Displays helpful messages for route mismatches
Provides link to troubleshooting documentation

⚠️ Production Reminder

Remember to set developerMode: false before deploying to production.

When developer mode is enabled, the debugging overlay is visible to all users. The overlay includes a reminder badge at the bottom to help you remember to disable it for production.

Best Practice - Use Environment Variables:

initXC(SITE_ID, API_KEY, {
  developerMode: process.env.NODE_ENV === "development", // Automatically false in production
  loginRoute: "/auth/login",
  signupRoute: "/auth/signup",
});

Or explicitly set it per environment:

// ✅ Development
initXC(SITE_ID, API_KEY, {
  developerMode: true,
  loginRoute: "/auth/login",
});

// ✅ Production
initXC(SITE_ID, API_KEY, {
  developerMode: false, // or simply omit this line
  loginRoute: "/auth/login",
});

Troubleshooting

Elements Not Being Detected

Symptoms:

Console warnings about missing elements
No tracking data being sent

Solutions:

Specify Custom Selectors if auto-detection fails:

Custom Selectors Example (Vanilla HTML)

If auto-detection fails, you can specify custom selectors in a plain HTML page like this:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>XC SDK - Custom Selector Example</title>
</head>
<body>
  <h2>Login Form</h2>
  <form>
    <input
      id="email-element-id"          <!-- emailElementSelector target -->
      type="email"
      placeholder="Email"
    />
    <input
      id="password-element-id"       <!-- passwordElementSelector target -->
      type="password"
      placeholder="Password"
    />
    <button
      id="submit-btn-id"        <!-- submitElementSelector target -->
      type="submit"
    >
      Login
    </button>
  </form>

  <script src="https://unpkg.com/@cross-classify/xc-sdk@latest/dist/xc-sdk.min.js"></script>
  <script>
      // Initialize XC SDK with custom selectors
      CrossClassify.initXC("YOUR_SITE_ID", "YOUR_API_KEY", {
         developerMode: true,
         loginRoute: LOGIN_ROUTE, // eg: "/auth/login"
         signupRoute: SIGNUP_ROUTE, // eg: "/auth/signup"

        formElementSelectors: {
          emailElementSelector: "#email-element-id",       // targets email input
          passwordElementSelector: "#password-element-id", // targets password input
          submitElementSelector: "#submit-btn-id"     // targets submit button
        }
      });
  </script>
</body>
</html>

Explanation:

The form elements are explicitly mapped using emailElementSelector, passwordElementSelector, and submitElementSelector.

Route Not Matched

Symptoms:

Overlay shows "Route Not Matched" with warning message
Form tracking is inactive
No tracking data being sent

Solutions:

1. Check Your Route Configuration

Ensure your routes match exactly with your application's URL paths:

initXC(SITE_ID, API_KEY, {
  developerMode: true,
  loginRoute: "/auth/login", // Must match your actual login page URL
  signupRoute: "/auth/signup", // Must match your actual signup page URL
});

2. Verify Route Matching

The SDK compares routes by stripping query parameters. For example:

Configured: /auth/login
Current URL: /auth/login?redirect=/dashboard ✅ Matches
Current URL: /auth/login/ ❌ Doesn't match (trailing slash)
Current URL: /login ❌ Doesn't match (different path)

3. Common Route Issues

Trailing slashes: /auth/login vs /auth/login/
Case sensitivity: /Auth/Login vs /auth/login
Query parameters: These are automatically ignored during matching
Hash fragments: These are automatically ignored during matching

4. AngularJS Hash-Mode Routes

AngularJS 1.x uses #!/login-style URLs by default. The SDK automatically extracts the path from the hash, so http://app.com/#!/login matches a loginRoute of "/login". If your routes still don't match, verify that the path after #! exactly matches your configured route (case-sensitive, no trailing slash).

5. Debug Route Matching

With developerMode: true, the overlay will show:

Current route being visited
Configured login/signup routes
Whether routes match or not
Visual indicators (green for matched, orange for unmatched)

No Data Being Sent

Check:

Verify your SITE_ID and API_KEY are correct
Ensure you're on the correct route (LOGIN_ROUTE or SIGNUP_ROUTE)
Check browser console for error messages
Verify form elements exist when initXC() is called
Use the developer overlay to verify route matching status

📋 Default Element Selectors

If you don't specify custom selectors formElementSelectors, the package will look for elements matching these patterns:

Email Fields (Required):

input[type="email"]
input[name*="email" i]
input[id*="email" i]
input[name*="user" i]
input[id*="login" i]
And many more common patterns...

Password Fields (Optional):

input[type="password"]
input[name*="pass" i]
input[id*="pass" i]
input[name*="secret" i]
And more...

Note: The password field is optional. The SDK will continue to function and track form interactions even if no password field is detected.

Submit Buttons (Required):

button[type="submit"]
input[type="submit"]
Elements with text containing "login", "signin", "submit", etc.
And more patterns...

🔄 API Reference

`initXC(siteId, apiKey, config)`

Initializes CrossClassify tracking for form analytics and user behavior monitoring.

Parameters:

siteId (number) - Required: Your unique site identifier from the CrossClassify dashboard
- Example: 12345
apiKey (string) - Required: Your API authentication key from the CrossClassify dashboard
- Example: "xc_live_abcd1234efgh5678ijkl"
config (object): Configuration object with the following properties:
Core Configuration
- developerMode (boolean) - Enable detailed console logging, debugging information, and visual element detection overlay (default: false)
- loginRoute (string) - Optional: URL path in your application where login forms are hosted (e.g., "/auth/login")
- signupRoute (string) - Optional: URL path in your application where signup forms are hosted (e.g., "/auth/register")
Note: At least one route (loginRoute or signupRoute) must be specified for the SDK to function. The SDK will only track forms when users visit these specified routes in your application.
Custom Element Selectors
- formElementSelectors (object) - Override default element detection:
  - emailElementSelector (string) - Required: CSS selector, ID selector, or text search for email field
  - passwordElementSelector (string) - Optional: CSS selector, ID selector, or text search for password field
  - submitElementSelector (string) - Required: CSS selector, ID selector, or text search for submit button
Note: The password field is optional. The SDK will work without it, tracking only email and submit interactions.
Advanced Configuration

Returns: void

Example:

initXC(12345, "xc_live_abcd1234efgh5678ijkl", {
  developerMode: true,
  loginRoute: "/auth/login",
  signupRoute: "/auth/register",
  formElementSelectors: {
    emailElementSelector: "#user-email",
    passwordElementSelector: "#user-password",
    submitElementSelector: "#login-button",
  },
});

Note: Replace the example values with your actual credentials from the CrossClassify dashboard.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

xc-sdk

🚀 Features

📦 Installation

NPM/Yarn

CDN

❓ How does this work?

🔧 Framework Integration

React

Angular

AngularJS (1.x)

⚙️ Configuration Options

Basic Configuration

Advanced Element Selection

Complete Configuration Example

🎯 Element Selection Methods

1. CSS and Id Selectors (Recommended)

2. Text Content Search

3. Fallback to Auto-Detection

🎯 Visual Element Detection Overlay

⚠️ Production Reminder

Troubleshooting

Elements Not Being Detected

Custom Selectors Example (Vanilla HTML)

Route Not Matched

No Data Being Sent

📋 Default Element Selectors

Email Fields (Required):

Password Fields (Optional):

Submit Buttons (Required):

🔄 API Reference

initXC(siteId, apiKey, config)

Core Configuration

Custom Element Selectors

Advanced Configuration

`initXC(siteId, apiKey, config)`