Package Exports

@ipranker/sdk

Readme

@ipranker/sdk

Professional IP Intelligence & Device Fingerprinting SDK

Single API call for comprehensive IP intelligence and fraud detection

Overview

IPRanker SDK provides a simple, one-line integration for advanced IP intelligence and fraud detection. With a single method call, you get comprehensive analysis including:

IP reputation and geolocation
Proxy, VPN, and Tor detection
Bot and automation detection
Device fingerprinting
Risk scoring

Features

✅ Simple Integration - One line of code to get started
✅ Comprehensive Analysis - IP intelligence + device fingerprinting + behavioral analysis
✅ TypeScript Support - Full type definitions included
✅ Lightweight - ~3 KB gzipped
✅ Framework Agnostic - Works with React, Vue, Angular, vanilla JS
✅ Privacy-Focused - No PII collection, GDPR compliant

Installation

npm

npm install @ipranker/sdk

yarn

yarn add @ipranker/sdk

CDN

<script src="https://unpkg.com/@ipranker/sdk"></script>

Quick Start

import IPRanker from '@ipranker/sdk';

// Initialize with your API key
const ipranker = new IPRanker('your-api-key-here');

// Analyze current visitor
const result = await ipranker.analyze();

console.log('Risk Score:', result.riskScore);
console.log('Location:', result.location.country);
console.log('Is Proxy:', result.threats.isProxy);

Usage Examples

Vanilla JavaScript

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@ipranker/sdk"></script>
</head>
<body>
  <button onclick="checkUser()">Analyze Visitor</button>

  <script>
    const ipranker = new IPRanker.IPRanker('your-api-key');

    async function checkUser() {
      const result = await ipranker.analyze();

      if (result.riskScore > 70) {
        alert('High risk user detected!');
      } else {
        console.log('User verified:', result);
      }
    }
  </script>
</body>
</html>

React

import { useState, useEffect } from 'react';
import IPRanker from '@ipranker/sdk';

function App() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    const ipranker = new IPRanker('your-api-key');

    const analyzeUser = async () => {
      setLoading(true);
      try {
        const data = await ipranker.analyze();
        setResult(data);
      } catch (error) {
        console.error('Analysis failed:', error);
      } finally {
        setLoading(false);
      }
    };

    analyzeUser();
  }, []);

  if (loading) return <div>Analyzing...</div>;

  return (
    <div>
      {result && (
        <>
          <p>Risk Score: {result.riskScore}/100</p>
          <p>Country: {result.location.country}</p>
          <p>City: {result.location.city}</p>
        </>
      )}
    </div>
  );
}

Vue 3

<template>
  <div>
    <div v-if="loading">Analyzing...</div>
    <div v-else-if="result">
      <p>Risk Score: {{ result.riskScore }}/100</p>
      <p>Country: {{ result.location.country }}</p>
      <p>City: {{ result.location.city }}</p>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import IPRanker from '@ipranker/sdk';

const loading = ref(false);
const result = ref(null);

onMounted(async () => {
  const ipranker = new IPRanker('your-api-key');
  loading.value = true;

  try {
    result.value = await ipranker.analyze();
  } catch (error) {
    console.error('Analysis failed:', error);
  } finally {
    loading.value = false;
  }
});
</script>

API Reference

Constructor

new IPRanker(apiKey: string, options?: IPRankerOptions)

Options

Option	Type	Default	Description
`collectBehavior`	`boolean`	`true`	Enable behavioral analysis
`behaviorTimeout`	`number`	`5000`	Max time to collect behavior (ms)
`cache`	`boolean`	`true`	Cache results locally
`cacheTimeout`	`number`	`300000`	Cache expiration (ms)
`debug`	`boolean`	`false`	Enable debug logging

Example

const ipranker = new IPRanker('your-api-key', {
  collectBehavior: true,
  behaviorTimeout: 3000,
  cache: false,
  debug: true
});

Methods

`analyze(options?): Promise<AnalysisResult>`

Analyzes the current visitor and returns comprehensive intelligence.

Parameters:

options (optional):
- ip?: string - Specific IP to analyze (otherwise auto-detected)
- includeRawData?: boolean - Include detailed raw data in response

Returns: Promise<AnalysisResult>

Example:

// Basic usage
const result = await ipranker.analyze();

// Analyze specific IP
const result = await ipranker.analyze({ ip: '8.8.8.8' });

// Include raw data
const result = await ipranker.analyze({ includeRawData: true });

`clearCache(): void`

Clears locally cached results.

ipranker.clearCache();

`destroy(): void`

Stops data collection and cleans up resources.

ipranker.destroy();

Response Format

interface AnalysisResult {
  success: boolean;
  ip: string;

  // Geolocation
  location: {
    country: string;
    countryCode: string;
    city: string;
    region: string;
    latitude: number;
    longitude: number;
    timezone: string;
    isp: string;
  };

  // Threat Detection
  threats: {
    isTor: boolean;
    isProxy: boolean;
    isVPN: boolean;
    isBot: boolean;
    isBlacklisted: boolean;
  };

  // Risk Assessment
  riskScore: number;        // 0-100 (higher = more risky)
  deviceTrust: number;      // 0-100 (higher = more trustworthy)

  timestamp: number;
}

Risk Score Interpretation

Score	Level	Description	Action
0-30	Low	Trusted user	Allow
31-60	Medium	Some suspicious signals	Monitor
61-80	High	Multiple risk factors	Challenge (CAPTCHA, 2FA)
81-100	Critical	Strong fraud indicators	Block or manual review

Use Cases

Fraud Prevention

const result = await ipranker.analyze();

if (result.riskScore > 70) {
  // Show CAPTCHA or additional verification
  showCaptcha();
} else if (result.threats.isProxy || result.threats.isVPN) {
  // Log for review
  logSuspiciousActivity(result);
} else {
  // Allow transaction
  processPayment();
}

Account Registration

const result = await ipranker.analyze();

if (result.threats.isBot) {
  return 'Bot detected. Please verify you are human.';
}

if (result.riskScore > 60) {
  // Require email verification
  requireEmailVerification();
}

// Proceed with registration
createAccount();

Content Access Control

const result = await ipranker.analyze();

if (result.threats.isTor) {
  return 'Access from Tor network is not allowed.';
}

if (result.location.countryCode === 'CN') {
  // Apply geo-restrictions
  showGeoblockedMessage();
}

// Grant access
showContent();

Event Callbacks

const ipranker = new IPRanker('your-api-key', {
  onReady: () => {
    console.log('SDK initialized');
  },
  onAnalyzing: () => {
    console.log('Analysis in progress...');
  },
  onComplete: (result) => {
    console.log('Analysis complete:', result);
  },
  onError: (error) => {
    console.error('Analysis failed:', error);
  }
});

Browser Support

Browser	Minimum Version
Chrome	90+
Firefox	88+
Safari	14+
Edge	90+
iOS Safari	14+
Android Chrome	90+

Privacy & Compliance

✅ No PII Collection - Only technical device characteristics
✅ GDPR Compliant - Can be used with cookie consent
✅ No Permissions Required - Works without browser prompts
✅ Secure - HTTPS only, no data stored on client

Performance

Bundle Size: ~3 KB gzipped
Initialization: < 10ms
Analysis Time: ~500ms average
Memory Usage: < 2 MB

Error Handling

try {
  const result = await ipranker.analyze();
  console.log(result);
} catch (error) {
  if (error.message.includes('API key')) {
    console.error('Invalid API key');
  } else if (error.message.includes('network')) {
    console.error('Network error - check connection');
  } else {
    console.error('Analysis failed:', error);
  }
}

TypeScript Support

Full TypeScript definitions are included:

import IPRanker, {
  AnalysisResult,
  IPRankerOptions
} from '@ipranker/sdk';

const options: IPRankerOptions = {
  collectBehavior: true,
  cache: false
};

const ipranker = new IPRanker('api-key', options);
const result: AnalysisResult = await ipranker.analyze();

Troubleshooting

"Invalid API key" Error

Make sure you're using a valid API key. Contact support to get your key.

Analysis Times Out

Try increasing the timeout:

const ipranker = new IPRanker('api-key', {
  behaviorTimeout: 10000  // 10 seconds
});

CORS Errors

Make sure your domain is whitelisted. Contact support to add your domain.

Support

Getting Help

📧 Email: support@ipranker.com
📚 Documentation: https://ipranker.com/docs
🐛 Issues: Report bugs via support email

Enterprise Support

For enterprise plans, custom features, or consulting:

📧 Enterprise: enterprise@ipranker.com
💼 Sales: sales@ipranker.com

Changelog

See CHANGELOG.md for version history and updates.

License

Made with ❤️ by the IPRanker Team