@datayield/react-sdk

React UI components for the DataYield consent-first data sovereignty platform. Drop these into any React app to add consent management, survey delivery, and premium feature gating — backed by the DataYield API.

What is DataYield?

DataYield is a consent-first data sovereignty layer for SaaS products. It gives users transparent control over which behavioral and profile data they share, rewards participation with premium access, and lets enterprises source that consented, anonymized data for AI training and analytics.

For your SaaS app this SDK handles:

1. Consent UI — users choose which data categories to share (behavioral, engagement, environment, profile, content). Nothing is collected without explicit opt-in.
2. Passive capture — the collector script (loaded separately) batches and sends only consented events to your DataYield project.
3. Survey delivery — multi-step survey modal loads questions from the API and submits answers.
4. Premium feature gating — useEntitlement checks whether a user has earned the premium tier via survey completion or contribution score.

Install

npm install @datayield/react-sdk@^2.0.0

Peer dependencies (install separately):

npm install react react-dom framer-motion

Prerequisites

Before using the SDK you need:

• A DataYield API endpoint (self-hosted or managed — https://api.yourdomain.com)
• A project with api_key and project_id (create via DataYield Admin or POST /v1/projects)
• Two JS files served from your app's public/ folder:
  • public/sdk/collector.js — passive behavioral capture
  • public/sdk/consent-gate.js — consent enforcement layer

Copy both files from the DataYield GitHub repo under frontend/public/sdk/.

Quick start (Next.js App Router)

// app/layout.tsx or app/page.tsx
import Script from 'next/script';
import { DataYieldProvider } from '@datayield/react-sdk';

export default function RootLayout({ children }) {
  return (
    <>
      {/* Load SDK scripts before React hydration */}
      <Script src="/sdk/collector.js" strategy="beforeInteractive" />
      <Script src="/sdk/consent-gate.js" strategy="beforeInteractive" />

      <DataYieldProvider
        config={{
          apiUrl: process.env.NEXT_PUBLIC_API_URL!,
          projectId: process.env.NEXT_PUBLIC_PROJECT_ID!,
          apiKey: process.env.NEXT_PUBLIC_API_KEY!,
          userId: currentUser?.id ?? null,
          accessToken: session?.access_token ?? null,
        }}
      >
        {children}
      </DataYieldProvider>
    </>
  );
}

.env.local:

NEXT_PUBLIC_API_URL=https://your-datayield-api.com
NEXT_PUBLIC_PROJECT_ID=your-project-id
NEXT_PUBLIC_API_KEY=your-api-key

For Vite, prefix with VITE_ and read with import.meta.env. For Create React App, prefix with REACT_APP_.

Components and hooks

DataYieldProvider

Context provider — wrap your app root. Calls window.DataYield.init and window.DataYieldConsent.configure when the scripts are loaded.

import { DataYieldProvider } from '@datayield/react-sdk';
import type { DataYieldConfig } from '@datayield/react-sdk';

Config:

| Prop | Type | Description | |------|------|-------------| | apiUrl | string | DataYield API base URL (no trailing slash) | | projectId | string | Project ID from DataYield Admin | | apiKey | string | API key from DataYield Admin (safe in client; treat like an embed key) | | userId | string \| null | Stable ID of the signed-in user | | accessToken | string \| null | Optional JWT — SDK adds Authorization: Bearer when set | | capture | object | Which data categories to allow for passive capture | | batchSize | number | Default: 20 | | flushIntervalMs | number | Default: 5000 | | sampling | number | 0–1 sampling rate. Default: 1 |

ConsentPopUp

Full-screen modal for first-visit consent + "Manage my data" entry point. Auto-shows on first visit unless dismissed; can be controlled programmatically.

import { ConsentPopUp } from '@datayield/react-sdk';

// First-visit auto-show:
<ConsentPopUp onSurveyTrigger={() => setShowSurvey(true)} />

// Controlled (e.g. "Manage my data" button):
<ConsentPopUp
  controlledVisible={manageOpen}
  onClose={() => setManageOpen(false)}
/>

Props: onConsentChange, onSurveyTrigger, storageKey, onClose, controlledVisible

ConsentBanner

Lightweight bottom-of-screen banner alternative to ConsentPopUp. Simpler UI, same consent flow.

import { ConsentBanner } from '@datayield/react-sdk';

<ConsentBanner onConsentChange={(types) => console.log(types)} />

SurveyModal

Multi-step survey modal. Loads questions from GET /v1/survey-questions, saves progress to localStorage, and submits to POST /v1/survey/submit. Requires profile consent.

import { SurveyModal } from '@datayield/react-sdk';

{showSurvey && (
  <SurveyModal
    onComplete={() => setShowSurvey(false)}
    onSkip={() => setShowSurvey(false)}
  />
)}

Supports question types: text, textarea, boolean, select, radio, multiselect, scale.

useEntitlement

Hook for gating premium features. Calls GET /v1/entitlements/me.

import { useEntitlement } from '@datayield/react-sdk';
import type { Entitlement } from '@datayield/react-sdk';

function PremiumFeature() {
  const { tier, hasAccess, loading, contribution_score } = useEntitlement('premium');

  if (loading) return <Spinner />;
  if (!hasAccess) return <UpgradePrompt score={contribution_score} />;
  return <PremiumContent />;
}

Putting it together

import {
  DataYieldProvider,
  ConsentPopUp,
  SurveyModal,
} from '@datayield/react-sdk';

function App() {
  const [showSurvey, setShowSurvey] = useState(false);

  return (
    <DataYieldProvider config={...}>
      <YourContent />

      <ConsentPopUp onSurveyTrigger={() => setShowSurvey(true)} />

      {showSurvey && (
        <SurveyModal
          onComplete={() => setShowSurvey(false)}
          onSkip={() => setShowSurvey(false)}
        />
      )}
    </DataYieldProvider>
  );
}

Tailwind

Components use Tailwind utility classes. If your app uses content for class extraction, include the SDK so classes are not purged:

// tailwind.config.js
export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@datayield/react-sdk/dist/**/*.{js,mjs}',
  ],
};

CORS

If your app's origin differs from the DataYield API host, register it in DataYield Admin → Allowed CORS Origins. Without this, browser fetch calls with x-api-key will be blocked.

API version compatibility

| SDK | DataYield API | |-----|---------------| | ^2.0.0 | 0.1.0 |

See packages/contracts/openapi.json for the checked-in OpenAPI spec and JSON schemas.

Full integration guide

docs/SAAS_INTEGRATION.md — step-by-step walkthrough including SDK script setup, CORS, environment variables, consent + survey flow, premium gating, and troubleshooting.

License

Proprietary — see repository root.