@ipranker/sdk

v1.3.0

Published

a month ago

Professional IP Intelligence and Device Fingerprinting SDK - Comprehensive fraud detection with single API call

@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();

if (result.success) {
  console.log('Location:', result.data.location);
  console.log('Is Proxy:', result.data.proxy.isProxy);
  console.log('Is Bot:', result.data.bot.isBot);
  console.log('Reputation:', result.data.reputation);
}

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.success) {
        const riskLevel = result.data.reputation.riskLevel;
        if (riskLevel === 'High' || riskLevel === 'Risky') {
          alert('High risk user detected!');
        } else {
          console.log('User verified:', result.data);
        }
      }
    }
  </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 && result.success && (
        <>
          <p>IP: {result.data.ip}</p>
          <p>Country: {result.data.location.country_name}</p>
          <p>City: {result.data.location.city}</p>
          <p>Is Proxy: {result.data.proxy.isProxy ? 'Yes' : 'No'}</p>
          <p>Risk Level: {result.data.reputation.riskLevel}</p>
        </>
      )}
    </div>
  );
}

Vue 3

<template>
  <div>
    <div v-if="loading">Analyzing...</div>
    <div v-else-if="result && result.success">
      <p>IP: {{ result.data.ip }}</p>
      <p>Country: {{ result.data.location.country_name }}</p>
      <p>City: {{ result.data.location.city }}</p>
      <p>Is Proxy: {{ result.data.proxy.isProxy ? 'Yes' : 'No' }}</p>
      <p>Risk Level: {{ result.data.reputation.riskLevel }}</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>

Angular

import { Component, OnInit } from '@angular/core';
import { CommonModule } from '@angular/common';
import IPRanker from '@ipranker/sdk';

@Component({
  selector: 'app-visitor-analysis',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div>
      <button (click)="analyze()" [disabled]="loading">
        {{ loading ? 'Analyzing...' : 'Analyze Visitor' }}
      </button>

      <div *ngIf="result && result.success">
        <p>IP: {{ result.data.ip }}</p>
        <p>Country: {{ result.data.location.country_name }}</p>
        <p>City: {{ result.data.location.city }}</p>
        <p>Is Proxy: {{ result.data.proxy.isProxy ? 'Yes' : 'No' }}</p>
        <p>Risk Level: {{ result.data.reputation.riskLevel }}</p>
      </div>
    </div>
  `
})
export class VisitorAnalysisComponent implements OnInit {
  loading = false;
  result: any = null;
  private ipranker = new IPRanker('your-api-key');

  async analyze() {
    this.loading = true;
    try {
      this.result = await this.ipranker.analyze();
    } catch (error) {
      console.error('Analysis failed:', error);
    } finally {
      this.loading = false;
    }
  }
}

📚 More Framework Examples

For complete, production-ready examples with services, guards, interceptors, and more:

📖 View All Framework Examples on IPRanker Docs

Interactive examples available for:

✅ Angular - Service, components, route guards, HTTP interceptors
✅ React - Hooks, context, custom hooks
✅ Vue - Composition API, Options API
✅ Vanilla JS - Plain JavaScript implementation

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: [email protected]
📚 Documentation: https://ipranker.com/docs
🐛 Issues: Report bugs via support email

Enterprise Support

For enterprise plans, custom features, or consulting:

📧 Enterprise: [email protected]
💼 Sales: [email protected]

Changelog

See CHANGELOG.md for version history and updates.

License

Made with ❤️ by the IPRanker Team

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@ipranker/sdk

Professional IP Intelligence & Device Fingerprinting SDK

Overview

Features

Installation

npm

yarn

CDN

Quick Start

Usage Examples

Vanilla JavaScript

React

Vue 3

Angular

📚 More Framework Examples

API Reference

Constructor

Options

Example

Methods

analyze(options?): Promise<AnalysisResult>

clearCache(): void

destroy(): void

Response Format

Risk Score Interpretation

Use Cases

Fraud Prevention

Account Registration

Content Access Control

Event Callbacks

Browser Support

Privacy & Compliance

Performance

Error Handling

TypeScript Support

Troubleshooting

"Invalid API key" Error

Analysis Times Out

CORS Errors

Support

Getting Help

Enterprise Support

Changelog

License

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

`clearCache(): void`

`destroy(): void`