Scam Alert Reporting Widget Documentation

Getting Started

What is the Scam Alert Widget?

The Scam Alert Widget is a lightweight, embeddable component that allows any website to provide scam reporting functionality directly on their platform. The widget opens a modal dialog containing an iframe that loads the complete Scam Report flow from Scam Alert, enabling your users to report suspicious services or lost funds without leaving your site.

Key Features

Framework Agnostic:: Works with React, Vue, Angular, vanilla JavaScript, or any web framework
TypeScript Support: Full type definitions available for enhanced development experience
Customizable:: Theme and language can be configured to match your brand
Multi-Language:: Supports multiple languages
Lightweight:: Minimal footprint with no external dependencies
Accessible:: Keyboard navigation and screen reader friendly
Mobile Responsive:: Works seamlessly across all device sizes

How It Works

The widget consists of a small JavaScript file (report-script.js) that you include on your website. When triggered, it creates a modal overlay containing an iframe that loads the Scam Alert reporting interface. The widget handles all communication between your site and the iframe, including language detection, theme customization, and submission notifications.

Integration

Get started with the widget in minutes. There are two ways to integrate: a minimal iframe embed or the enhanced modal experience with full customization.

Option 1: Minimal Iframe Embed

The simplest way to add the widget is with a direct iframe embed. Just add this to your HTML:

<iframe 
  src="https://scam-alert.io/widget?access_key=pk_1234567890&hostname=example.com" 
  width="100%" 
  height="600px"
  style="border: none; border-radius: 8px;"
  title="Report a Scam"
></iframe>

Pros: Zero JavaScript, works immediately, perfect for simple integrations
Cons: No modal overlay, no theme customization, no callbacks

Option 2: Enhanced Modal Experience (Recommended)

For a better user experience with modal overlay, theme customization, and callbacks, use the integration script:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Scam Alert Widget Demo</title>
  <!-- Load the widget script -->
  <script src="https://scam-alert.io/widget/report-script.js"></script>
</head>
<body>
  <h1>Report a Scam</h1>
  <button onclick="window.openScamAlertWidget('https://scam-alert.io/widget', 'pk_1234567890')">
    Report Scam
  </button>
</body>
</html>

Benefits: Modal overlay that appears on top of your page | Automatic language detection from your site | Theme customization to match your brand | Callback notifications when reports are submitted | Keyboard support (Escape to close) | Scroll locking while modal is open

Modal overlay that appears on top of your page
Automatic language detection from your site
Theme customization to match your brand
Callback notifications when reports are submitted
Keyboard support (Escape to close)
Scroll locking while modal is open

What You'll Need

Component	Description
report-script.js	The main integration script that exposes the widget API and handles modal rendering. Hosted at `scam-alert.io/widget/report-script.js`
Widget endpoint	The report flow interface loaded inside the modal iframe. Hosted at `scam-alert.io/widget`
Your access key	The access key you receive from Scam Alert when you register your website as our partner.
Your integration	A button or trigger on your site that calls the widget API

TypeScript Support

Step 1: Create Type Definitions

Create a .d.ts file in your project (e.g., src/types/scam-widget.d.ts):

// scam-widget.d.ts
interface WidgetTheme {
  'bg-brand'?: string;       
  'text-brand'?: string;     
  'bg-primary'?: string;     
  'text-primary'?: string;   
  'bg-secondary'?: string;   
  'text-secondary'?: string; 
  'bg-tertiary'?: string;    
  'text-tertiary'?: string;  
  'bg-input'?: string;       
  'text-input-placeholder'?: string; 
  'error-text'?: string;     
  border?: string;           
}

interface WidgetOptions {
  theme?: WidgetTheme;
  lang?: string;
}

interface Window {
  openScamAlertWidget: (url: string, access_key: string, options?: WidgetOptions) => void;
  closeScamAlertWidget: () => void;
  onScamAlertReportSubmit?: () => void;
}

Step 2: Update tsconfig.json

Ensure the type definitions are included in your TypeScript configuration:

{
  "compilerOptions": {
    "types": ["./types/scam-widget"]
  },
  "include": ["src/**/*", "types/**/*"]
}

Framework Examples

The widget works seamlessly with popular JavaScript frameworks. Here are examples for some:

import { useEffect } from 'react';

export function ReportButton() {
  useEffect(() => {
    window.onScamAlertReportSubmit = () => {
      console.log('Report submitted!');
    };
  }, []);

  const handleReport = () => {
    window.openScamAlertWidget('https://scam-alert.io/widget', 'pk_1234567890', {
        theme: {
            'bg-brand': '#3b82f6',
            'bg-primary': '#ffffff',
            'text-primary': '#1f2937',
        },
        lang: 'en',
    });
  };

  return <button onClick={handleReport}>Report a Scam</button>;
}

<script setup lang="ts">
import { onMounted } from 'vue';

onMounted(() => {
  window.onScamAlertReportSubmit = () => {
    console.log('Report submitted!');
  };
});

const openWidget = () => {
    window.openScamAlertWidget('https://scam-alert.io/widget', 'pk_1234567890', {
      lang: 'en',
    });
};
</script>

<template>
  <button @click="openWidget">Report a Scam</button>
</template>

import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-report-button',
  template: `<button (click)="openWidget()">Report a Scam</button>`
})
export class ReportButtonComponent implements OnInit {
  ngOnInit() {
    window.onScamAlertReportSubmit = () => {
      console.log('Report submitted!');
    };
  }

  openWidget() {
    window.openScamAlertWidget('https://scam-alert.io/widget', 'pk_1234567890', {
        lang: 'en',
    });
  }
}

Theme

The widget exposes a simple, well-documented API for opening, closing, and customizing the modal behavior.

Method / Property	Description
openScamAlertWidget(url, access_key, options?)	Opens the widget modal. The `url` parameter should point to the widget endpoint (e.g.,'https://scam-alert.io/widget'). Optional `options` object can include`theme` and `lang` properties..
closeScamAlertWidget()	Closes the widget modal and restores page scroll behavior.
window.onScamAlertReportSubmit	Optional callback function that is called when a report is successfully submitted. Define this function to track analytics or show confirmation messages.

The widget can be customized to match your brand's look and feel, and supports multiple languages for international audiences.

You can override the widget's default theme by passing a theme object when opening the widget:

// Pass theme when opening the widget
window.openScamAlertWidget('https://scam-alert.io/widget', 'pk_1234567890', {
  theme: {
    'bg-brand': '#22c55e',
    'bg-primary': '#ffffff',
    'bg-secondary': '#f9fafb',
    'text-primary': '#111827',
    'text-secondary': '#6b7280',
    border: '#e5e7eb'
  }
});

Supported Theme Properties

The widget supports the following theme keys, each mapping to one or more CSS variables:

Property Key	Maps to CSS Variables	Description
bg-brand	`--primary`, `--primary-hover`, `--primary-active`, `--ring`	Primary brand color (buttons, links, focus rings)
text-brand	`--primary-foreground`	Text color for brand elements
bg-primary	`--card`	Primary background for cards and containers
text-primary	`--card-foreground`	Primary text color for cards
bg-secondary	`--popover`, `--skeleton`	Secondary background for popovers and skeleton loaders
text-secondary	`--card-muted-foreground`, `--popover-foreground`, `--tertiary-foreground`, `--card-tertiary-foreground`	Secondary/muted text color
bg-tertiary	`--widget-inactive-step-background`, `--secondary`	Tertiary background for inactive steps
text-tertiary	`--widget-inactive-step-foreground`	Tertiary text color for inactive steps
bg-input	`--input`	Input field background
text-input-placeholder	`--muted-foreground`	Input field placeholder text color
error-text	`--destructive`	Error message and destructive action color
Border	`--border`	Border color for all elements

Color Formats: Values can be in any valid CSS color format including hex, RGB, RGBA, HSL, HSLA or named colors. Invalid values are sanitized for security.

Language

The widget automatically detects and respects the language of your website. The precedence order is:

options.lang parameter passed to openScamAlertWidget()
The host page's <html lang="..."> attribute
The user's browser language settings

Example

// Explicit language setting
window.openScamAlertWidget('https://scam-alert.io/widget', 'pk_1234567890', { 
  lang: 'es' 
});

// Automatic detection from <html lang="fr">
window.openScamAlertWidget('https://scam-alert.io/widget', 'pk_1234567890');