Device Intelligence SDK

This README explains how to integrate Device Intelligence SDK into your app. It covers setup, login/signup flows, where to place your custom logic, and a placeholder for transactions.

Table of Contents

1. Installation / prerequisites
2. Quick setup (sdk-utils.js)
3. App integration (app.js)
4. Sign-in flow
5. Sign-up flow
6. Transaction placeholder
7. API reference (used functions)
8. Troubleshooting & tips

1. Installation / prerequisites

• Install SDK:

  npm install device-intelligence-sdk --registry http://10.10.10.97:4873
  
  

• Project must support ES modules.

• Ensure your serverUrl is correct and reachable.

• Example environment:

  • React (hooks used in snippets)
  • A reachable Device Intelligence server (http://localhost:8010?EIO=4&transport=websocket in dev)

2. Quick setup (sdk-utils.js)

Create a shared SDK instance for your app:

// sdk-utils.js
import { DeviceIntelligenceSDK } from "device-intelligence-sdk";

export const devIntelligenceSdk = DeviceIntelligenceSDK({
  productId: "proj_456",
  serverUrl: "http://localhost:8010?EIO=4&transport=websocket",
});

3. App integration (app.js)

Start SDK once and subscribe to alerts:

// app.js
import React, { useEffect } from "react";
import { devIntelligenceSdk } from "./sdk-utils";

function App() {
  useEffect(() => {
    let subscription;

    devIntelligenceSdk.start()
      .then(() => {
        subscription = devIntelligenceSdk.getGlobalAlertListener().subscribe((data) => {
          console.log("Alert from Global Listener", data);
          // === CUSTOM LOGIC PLACE ===
          // Example: show toast, open alert modal, block UI, or log analytics
        });
      })
      .catch((error) => {
        console.error("SDK failed to start:", error);
      });

    return () => {
      if (subscription?.unsubscribe) {
        subscription.unsubscribe();
      }
    };
  }, []);

  return <h1>My App</h1>;
}

export default App;

4. Sign-in flow

const signin = async () => {
  try {
    const resp = await devIntelligenceSdk.trackLoginAsync({ userId: email });
    console.log("login response", resp);

    if (resp.action === "Alert") {
      alert(
        `Alert: Detected ${resp.casesPassed[0].condition.left.name} : ${resp.casesPassed[0].actual}. But login to Continue`
      );

      // === CUSTOM LOGIC PLACE ===
      // Example: require 2FA, log event, or show warning modal
      devIntelligenceSdk.trackLoginSuccess({});
      navigate("/dashboard");

    } else if (resp.action === "Block") {
      alert(
        `Block: Detected ${resp.casesPassed[0].condition.left.name} : ${resp.casesPassed[0].actual}. Login Blocked`
      );

      // === CUSTOM LOGIC PLACE ===
      // Example: show error view, log to monitoring system
      devIntelligenceSdk.trackLoginFail({ reason: "Block Detected" });

    } else {
      // Allow
      devIntelligenceSdk.trackLoginSuccess({});
      navigate("/dashboard");
    }
  } catch (error) {
    console.error("signin error:", error);
    // === CUSTOM LOGIC PLACE ===
    // Example: show error to user or retry
  }
};

5. Sign-up flow

const signup = () => {
  devIntelligenceSdk.updateUserId(email);

  devIntelligenceSdk.trackSignUp({
    promoCodeUsed: promoCode,
  });

  // === CUSTOM LOGIC PLACE ===
  // Example: validate promo, run extra verification
  devIntelligenceSdk.trackSignUpSuccess({
    promoCodeUsed: promoCode,
  });

  navigate("/dashboard");
};

6. Transaction flow

The SDK supports async transaction tracking with alert/block decisions, similar to login.

const submitTransaction = async (txPayload) => {
  try {
    const resp = await devIntelligenceSdk.trackTransactionAsync({
      txnId: txPayload.txnId,
      transactionType: txPayload.type,
      amount: txPayload.amount,
      currency: txPayload.currency,
      userId: email,
    });

    if (resp.action === "Alert") {
      alert(`Transaction Alert: ${resp.casesPassed[0].condition.left.name} → ${resp.casesPassed[0].actual}`);
      // === CUSTOM LOGIC PLACE ===
      // Example: require OTP, pause transaction for manual review
      devIntelligenceSdk.trackTransactionSuccess({
        txnId: txPayload.txnId,
        amount: txPayload.amount,
      });
    } else if (resp.action === "Block") {
      alert(`Transaction Blocked: ${resp.casesPassed[0].condition.left.name}`);
      // === CUSTOM LOGIC PLACE ===
      devIntelligenceSdk.trackTransactionFail({
        txnId: txPayload.txnId,
        reason: "Blocked by rules",
      });
    } else {
      // Allow
      devIntelligenceSdk.trackTransactionSuccess({
        txnId: txPayload.txnId,
        amount: txPayload.amount,
      });
    }
  } catch (error) {
    console.error("Transaction error:", error);
    devIntelligenceSdk.trackTransactionFail({
      txnId: txPayload.txnId,
      reason: "SDK error",
    });
  }
};

7. API reference (used functions)

| Function | Description | | ---------------------------------------- | ---------------------------------------------------- | | DeviceIntelligenceSDK(config) | Create SDK instance with { projectId, serverUrl }. | | start() | Start SDK and connect. | | getGlobalAlertListener().subscribe(cb) | Subscribe to global alerts. | | trackLoginAsync({ userId }) | Send login attempt and return decision. | | trackLoginSuccess(meta) | Notify successful login. | | trackLoginFail({ reason }) | Notify failed login. | | updateUserId(userId) | Update user identifier. | | trackSignUp(meta) | Track signup attempt. | | trackSignUpSuccess(meta) | Notify signup success. | | trackTransactionAsync(params) | Send transaction attempt and return decision. | | trackTransactionSuccess(params) | Notify successful transaction. | | trackTransactionFail(params) | Notify failed transaction. |

8. Troubleshooting & tips

• SDK fails to start → check serverUrl and use wss:// in production if needed.
• No alerts → ensure subscription happens after start().
• Duplicate alerts → export a singleton SDK instance and clean up listeners.
• Testing → use staging projectId to simulate Alert and Block.
• Security → never expose secrets; projectId is safe to embed.
• Logging → inspect resp from trackLoginAsync to understand backend decisions.

Custom logic summary

• Global alerts: show toast, block actions, log.
• Sign-in Alert: require 2FA, log warning, allow with caution.
• Sign-in Block: stop login, show error, track failure.
• Sign-up: validate promo, verify user, decide success/fail.
• Transactions: Transactions: handle allow/alert/block before committing.