satyamark-react

Real-time content verification library for React applications

SatyaMark is an enterprise-grade React SDK that provides real-time verification for text and image content through AI-powered fact-checking, deepfake detection, and fake news identification. It seamlessly injects transparent trust signals and content credibility indicators directly into your UI, allowing your users to distinguish between reliable information and misinformation.

Installation

npm install satyamark-react

Peer Dependency: React 18+

Quick Start

1. Initialize Connection

Note: During the current phase, you may provide any arbitrary app_id and user_id. We recommend using a snake_case version of your project name for the app_id, and a stable, unique identifier for the user_id.

import { useEffect } from "react";
import { init } from "satyamark-react";

function App() {
  useEffect(() => {
    init({
      app_id: "your-app-id",
      user_id: "unique-user-id", // Use stable unique user id
    });
  }, []);

  return <YourAppContent />;
}

Optional: onConnected

onConnected notifies when the connection state changes.

Callback receives:

{
  app_id: string;
  user_id: string;
}

If disconnected or closed, it receives null.

import { useEffect } from "react";
import { init, onConnected } from "satyamark-react";

function App() {
  useEffect(() => {
    init({
      app_id: "my-app",
      user_id: "user_123",
    });

    const unsubscribe = onConnected((connection) => {
      if (connection) {
        console.log("Connected:", connection.app_id, connection.user_id);
      } else {
        console.log("Disconnected");
      }
    });

    return unsubscribe;
  }, []);

  return <YourApp />;
}

2. Process a Content Element

import { useRef, useEffect } from "react";
import { process } from "satyamark-react";

function PostCard({ post }) {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!ref.current) return;
    try {
      process(ref.current, post.id);
    } catch (error) {
      console.log(error);
    }
  }, [post.id]);

  return (
    <div ref={ref}>
      <p>{post.text}</p>
      {post.image && <img src={post.image} alt="" />}

      <div data-satyamark-status-container />
    </div>
  );
}

You can style the data-satyamark-status-container element according to your UI requirements.

Core Concepts

SatyaMark consists of three core modules that work together:

1. Connection Layer

• Authenticates with your app_id and user_id
• Maintains persistent WebSocket connection
• Handles incoming verification results

2. Processing Layer

• Walks the DOM tree to extract visible text
• Finds and validates images
• Sends content to verification service
• Internally tracks verification jobs

3. Status Layer

• Automatically injects verification icons into your UI
• Updates status in real-time
• Provides tooltips on hover
• Makes icons clickable for detailed results

Lifecycle Flow

1. init()      → Establish connection
2. render      → Display content normally
3. process()   → Extract content & auto-inject verification status

All retries, result handling, and UI updates are managed internally.

API Reference

1. init(connectionData)

Establishes WebSocket connection.

Parameters

• app_id: string — Unique identifier for your application
• user_id: string — Unique identifier for the current user

2. onConnected(callback)

Listens for connection state changes.

Callback receives:

  {
    app_id: string;
    user_id: string;
  }

Returns null if disconnected.

3. process(rootElement, dataId)

Extracts text and images from a DOM element and submits them for verification.

Parameters

• rootElement: HTMLDivElement — DOM element containing the content
• dataId: string — Unique identifier for this specific content item

Verification Marks

SatyaMark displays different marks based on verification results:

| Mark | Meaning | |------|---------| | ✅ Verifiable | Content contains factual claims that can be verified | | ❌ Unverifiable | Cannot be verified (opinions, random data, etc.) | | ⚠️ Insufficient | Verifiable but not enough reliable sources available | | ✔️ Correct | Factually correct based on evidence | | ❗ Incorrect | Factually incorrect or contradicts sources | | ⏳ Pending | Verification in progress | | 🤖 AI-Generated | Media appears to be AI-generated | | 👤 Human-Generated | Media appears to be human-created | | ❓ Uncertain | Cannot confidently determine AI vs human origin |

Interactive: After verification completes, clicking the mark opens a detailed results page with sources and evidence.

Best Practices

Do

• Initialize init() once in your root App component
• Use a unique and stable user_id when calling init()
• Use a stable and unique dataId for each content item (database IDs recommended)
• Call process() only after the element is mounted
• Include data-satyamark-status-container where you want status displayed
• Style the data-satyamark-status-container element as per your UI requirements
• Optionally use onConnected() if your UI depends on connection readiness
• Let SatyaMark manage verification lifecycle and retries internally

Don't

• Don't call init() multiple times or in multiple components
• Don't use random or changing user_id values for the same user session
• Don't use random or changing dataId values for the same content
• Don't manually retry process() in loops
• Don't call process() before the element exists in the DOM

Performance Tips

• Debounce Input Changes - Avoid re-processing content on every keystroke
• Process Visible Content Only - Use Intersection Observer for large feeds
• Prevent Re-Render Loops - Ensure process() isn’t triggered repeatedly by state updates
• Use Stable Content Identifiers - Prevent duplicate or unnecessary verification calls

Troubleshooting

System Status Check: If you are experiencing unexpected behavior or connectivity issues, you can verify whether our core services are operational by testing the chat demo on the SatyaMark website. If the demo is also unresponsive, we may be experiencing a temporary service degradation. We apologize for any disruption and appreciate your patience as we restore full functionality. For further support, please contact [email protected].

1. Invalid root element

Cause: Calling process() with null/undefined ref.

Solution: Check ref exists before processing:

if (!ref.current) return;
try {
  process(ref.current, post.id);
} catch (error) {
  console.log(error);
}

2. No valid text or image found

Cause: Element contains no extractable content or all images fail to load.

Solution: Ensure content has visible text (3+ chars) or valid image URLs.

3. Status icon not appearing

Cause: Missing data-satyamark-status-container or process() not executed.

Solution: Ensure:

- `init()` was called
- `process()` ran after the element mounted
- `data-satyamark-status-container` exists inside the processed element

4. Connection fails or times out

Cause: Network issues, invalid credentials, or server unavailable.

Solution: Check console for WebSocket errors. Verify app_id and user_id are correct.

5. Verification stuck on "Pending"

Cause: Server processing delay.

Solution: Verification can take a few seconds to a few minutes depending on content complexity and system load.

Contributing

SatyaMark is fully open-source and welcomes contributions!

How to Contribute

• Report bugs on GitHub Issues
• Request features that align with the project's mission
• Improve documentation - submit PRs for clarity improvements
• Contribute code - follow the contributing guidelines in the repository
• Share feedback on library design and API

Project Links

• Main Repository: github.com/DhirajKarangale/SatyaMark
• npm Package: npmjs.com/package/satyamark-react
• Demo Application: SatyaMark

All contributions are reviewed for alignment with SatyaMark's principles: transparency, evidence-based verification, and accessibility.

License

MIT © SatyaMark Contributors