Visual Discovery SDK

A standalone, zero-dependency JavaScript SDK for integrating visual search and object detection into e-commerce storefronts.

Features

  • Zero Dependencies: Pure vanilla JavaScript.
  • Multi-Language Support: Auto-detects or configures EN, DE, ES, FR, TR.
  • Visual Search: Upload or capture images to find similar products.
  • Object Detection: Automatically identifies multiple fashion items in a single photo.
  • Drill-down Discovery: Users can click "Show Similar" on specific results.
  • GA4 Integration: Built-in event tracking for Google Analytics 4.

Quick Start

1 Include the SDK

Include the script at the end of your <body> tag.

<script src="https://visualdiscovery.net/sdk.js"></script>

2 Initialize

Initialize the SDK with your configuration.

window.VisualDiscovery.init({
    apiBaseUrl: 'https://api.visualdiscovery.net/v1',
    accountId: 'YOUR_ACCOUNT_ID', // Required
    themeColor: '#4f46e5',        // Optional: Theme color
    language: 'en',               // Optional: Auto-detect or override
    limit: 24                     // Optional: Items per page
});

3 Trigger the Modal

You can open the modal programmatically via your own buttons:

// Example: Bind to a nav button
document.getElementById('my-search-btn').addEventListener('click', () => {
    window.VisualDiscovery.open();
});

API Interaction Details

The SDK communicates with the backend via three primary endpoints.

POST /discover/detect

1. Detect Objects

  • Trigger: User uploads a file.
  • Purpose: Uploads raw image to identify bounding boxes.
  • Payload: FormData (file, account_id).
  • Response: Returns request_id and detections.
GET /discover/search

2. Search by Crop

  • Trigger: User clicks a detected object crop or changes filter.
  • Purpose: Finds products visually similar to the specific crop.
  • Parameters: request_id, x1,y1,x2,y2, search, limit.
GET /discover/similar

3. Find Similar Products (Deep Dive)

  • Trigger: User clicks the "Show Similar" icon on a result.
  • Purpose: Finds products similar to an existing inventory item.
  • Parameters: id, search, limit.

Data Flow & Architecture

The SDK facilitates a conversation between the User, the Client Browser, and the Backend API.

sequenceDiagram autonumber actor User participant SDK as SDK (Client) participant API as Visual Discovery API Note over User, SDK: Initialization Phase User->>SDK: Triggers Open() SDK->>User: Displays Upload/Camera UI Note over User, SDK: Detection Phase User->>SDK: Uploads Image SDK->>API: POST /discover/detect (Image + AccountID) activate API API-->>SDK: 200 OK (Detections + RequestID) deactivate API SDK->>User: Displays Detected Object Crops Note over User, SDK: Search Phase User->>SDK: Selects a Crop (Box) SDK->>API: GET /discover/search (RequestID + Coordinates) activate API API-->>SDK: 200 OK (Product List) deactivate API SDK->>User: Displays Product Grid alt Text Refinement User->>SDK: Types keyword (e.g., "Red") SDK->>API: GET /discover/search (RequestID + Coords + SearchTerm) API-->>SDK: 200 OK (Filtered Product List) SDK->>User: Updates Grid end alt Deep Dive (Show Similar) User->>SDK: Clicks "Show Similar" Icon on Product A SDK->>API: GET /discover/similar (ProductID_A + SearchTerm) activate API API-->>SDK: 200 OK (Similar Products to A) deactivate API SDK->>User: Updates Grid with new results end

CSS & Styling

The SDK injects styles with .vd- prefix.

  • Z-Index: Modal uses z-index: 9999.
  • Fonts: Inherits system fonts (Inter, -apple-system).
  • Responsive: Grid adapts to screen size.

GA4 Events

Pushes to window.gtag or dataLayer.

Event Desc
visual_discovery_open Modal opened.
view_item_list Results loaded.
select_item Card clicked.

🔒 Privacy & Security

  • Ephemeral Processing: Images are processed in memory and not permanently stored unless opted-in.
  • No Facial Recognition: Strictly tuned for fashion objects; no biometric data.
  • Encryption: Data in transit encrypted via TLS 1.3.