@dataclaus/sdk-react-native

React Native SDK for DataClaus - Monetize user data fairly with revenue sharing.

Overview

DataClaus enables developers to share advertising and data revenue with their users. This SDK provides:

• User Identity Linking - Connect your users to DataClaus accounts for earnings tracking
• Ad Revenue Components - Banner, interstitial, and rewarded ads with automatic revenue sharing
• Sensor Data Collection - Collect behavioral data to earn from data marketplace
• Fraud Detection - AI-powered bot detection to ensure payouts go to real humans

Installation

npm install @dataclaus/sdk-react-native
# or
yarn add @dataclaus/sdk-react-native

Peer Dependencies

npm install react react-native

Optional Dependencies

For enhanced device fingerprinting:

npm install react-native-device-info

For sensor data collection:

npm install expo-sensors

Quick Start

1. Link Users

After user authentication, link them to DataClaus:

import { useIdentity } from '@dataclaus/sdk-react-native';

function AfterLogin({ user }) {
  const { linkUser, isLinked, earnings } = useIdentity({
    apiUrl: 'https://api.dataclaus.io',
    applicationId: 'YOUR_APP_ID',
  });

  useEffect(() => {
    linkUser({
      externalUserId: user.id,
      email: user.email, // Optional, helps cross-app matching
    });
  }, [user]);

  return (
    <View>
      {isLinked && (
        <Text>You've earned ${earnings?.totalEarned ?? 0}</Text>
      )}
    </View>
  );
}

2. Display Ads

Wrap your app with AdProvider and display ads:

import { AdProvider, BannerAd, useRewardedAd } from '@dataclaus/sdk-react-native';

// In your app root
function App() {
  const { linkedUser } = useIdentity({ ... });
  
  if (!linkedUser) return <LoginScreen />;
  
  return (
    <AdProvider config={{
      apiUrl: 'https://api.dataclaus.io',
      applicationId: 'YOUR_APP_ID',
      userToken: linkedUser.userToken,
      testMode: __DEV__,
    }}>
      <Navigation />
    </AdProvider>
  );
}

// In your screens
function HomeScreen() {
  const { isLoaded, load, show } = useRewardedAd({
    onRewarded: (reward) => {
      // Give user in-app currency
      addCoins(reward.amount);
    },
    onPaidEvent: (impression) => {
      console.log(`Ad earned $${impression.revenue}`);
    },
  });

  useEffect(() => { load(); }, []);

  return (
    <SafeAreaView>
      {/* Banner at bottom of screen */}
      <BannerAd size="banner" />
      
      {/* Rewarded ad button */}
      <TouchableOpacity 
        onPress={show} 
        disabled={!isLoaded}
      >
        <Text>Watch Ad for 50 Coins</Text>
      </TouchableOpacity>
    </SafeAreaView>
  );
}

3. Collect Sensor Data (Optional)

For higher earnings, collect behavioral data:

import { useDataClaus, useSensorTracking } from '@dataclaus/sdk-react-native';
import { Accelerometer, Gyroscope } from 'expo-sensors';

function DataCollection() {
  const { collector, startCollection, stopCollection } = useDataClaus({
    backendUrl: 'https://your-backend.com',
    userId: user.id,
    debug: __DEV__,
  });

  // Auto-track sensors
  useSensorTracking(collector, { Accelerometer, Gyroscope });

  useEffect(() => {
    startCollection();
    return () => stopCollection();
  }, []);

  return <YourApp />;
}

API Reference

User Identity

useIdentity(config)

React hook for user identity management.

interface UserIdentityConfig {
  apiUrl: string;           // DataClaus API URL
  applicationId: string;    // Your app ID from dashboard
  debug?: boolean;          // Enable console logging
}

interface UseIdentityResult {
  linkedUser: LinkedUser | null;
  linkUser: (request: LinkUserRequest) => Promise<LinkedUser>;
  earnings: UserEarnings | null;
  refreshEarnings: () => Promise<void>;
  isLoading: boolean;
  isLinked: boolean;
  logout: () => void;
  error: string | null;
}

linkUser(request)

Links an external user to DataClaus.

interface LinkUserRequest {
  externalUserId: string;    // Your user ID
  email?: string;            // Optional email for cross-app matching
  phone?: string;            // Optional phone for matching
}

interface LinkedUser {
  dataclausUserId: string;
  userToken: string;         // Use for ad requests
  isNewUser: boolean;
  walletId: string;
}

Ads

AdProvider

Context provider for ads.

<AdProvider config={{
  apiUrl: string;
  applicationId: string;
  userToken: string;
  testMode?: boolean;      // Default: true
  debug?: boolean;
}}>
  {children}
</AdProvider>

BannerAd

Display a banner advertisement.

<BannerAd
  size="banner" | "largeBanner" | "mediumRectangle" | "adaptive"
  onAdLoaded={() => {}}
  onAdError={(error) => {}}
  onPaidEvent={(impression) => {}}
  style={ViewStyle}
/>

useInterstitialAd()

Hook for full-screen interstitial ads.

const { isLoaded, isLoading, load, show, error } = useInterstitialAd();

// Load when screen mounts
useEffect(() => { load(); }, []);

// Show at natural break point
const handleLevelComplete = () => {
  if (isLoaded) show();
};

useRewardedAd(options)

Hook for rewarded ads where users watch for rewards.

const { isLoaded, load, show, reward } = useRewardedAd({
  onRewarded: (reward) => {
    console.log(`User earned ${reward.amount} ${reward.type}`);
  },
  onPaidEvent: (impression) => {
    console.log(`Ad revenue: $${impression.revenue}`);
  },
});

Data Collection

useDataClaus(config)

Main hook for data collection.

const {
  collector,
  isCollecting,
  startCollection,
  stopCollection,
  trackScreenView,
  trackCustomEvent,
} = useDataClaus({
  backendUrl: string;
  userId: string;
  sessionId?: string;
  collectionInterval?: number;  // Default: 100ms
  batchSize?: number;           // Default: 50 events
  flushInterval?: number;       // Default: 5000ms
  debug?: boolean;
});

useSensorTracking(collector, sensors)

Automatically tracks accelerometer and gyroscope data.

import { Accelerometer, Gyroscope } from 'expo-sensors';

useSensorTracking(collector, { Accelerometer, Gyroscope }, {
  interval: 100,  // Collection interval in ms
});

Fraud Detection

useFraudDetection(config)

Monitor for bot/emulator signals.

const { fraudScore, isBot, signals } = useFraudDetection({
  sensitivityLevel: 'medium',
});

if (isBot) {
  // Don't send data - won't earn rewards anyway
}

Revenue Distribution

When ads are shown, revenue is split automatically:

| Recipient | Share | Example ($10 CPM) | |-----------|-------|-------------------| | User | 50-90% (configurable) | $7.00 | | Developer | 5-45% | $2.50 | | Platform | 5% (fixed) | $0.50 |

Configure your app's revenue share in the DataClaus dashboard.

Best Practices

1. Always Link Users First

Ads won't track properly without a linked user:

// ❌ Bad - ads won't attribute revenue
<AdProvider userToken="">
  <BannerAd />
</AdProvider>

// ✅ Good - wait for user linking
{linkedUser && (
  <AdProvider userToken={linkedUser.userToken}>
    <BannerAd />
  </AdProvider>
)}

2. Use Test Mode in Development

<AdProvider config={{
  ...config,
  testMode: __DEV__, // Uses test ads and simulated revenue
}}>

3. Handle Offline Gracefully

const { error } = useIdentity(config);

if (error) {
  // Still let users use the app
  return <OfflineMode />;
}

4. Preload Rewarded Ads

// Load immediately when screen mounts
useEffect(() => { 
  load(); 
}, []);

// Reload after showing
const handlePress = async () => {
  await show();
  load(); // Preload next ad
};

TypeScript Support

This package includes TypeScript definitions. All exports are fully typed.

import type { 
  LinkedUser, 
  UserEarnings, 
  AdImpression, 
  AdType 
} from '@dataclaus/sdk-react-native';

Troubleshooting

"Ads not enabled for this application"

1. Check your applicationId is correct
2. Ensure ads are enabled in the dashboard
3. Verify your app is approved for production ads

"Failed to link user"

1. Check network connectivity
2. Verify apiUrl points to correct server
3. Check application ID matches dashboard

Low Quality Score

Users with scores below 0.5 don't earn rewards:

• Encourage natural app usage
• Don't incentivize fake engagement
• Our AI detects automated patterns

Support

• Documentation: docs.dataclaus.io
• Dashboard: dashboard.dataclaus.io
• Discord: discord.gg/dataclaus
• Email: [email protected]

License

MIT © DataClaus