Pinglet SDK Documentation

Overview

Pinglet is a real-time notification platform that lets you send push notifications, glassmorphism card notifications, and custom template notifications to your users with a single API call. In v0.0.3, all in-app types use a unified glassmorphism renderer. The SDK connects via SSE (Server-Sent Events) for instant delivery.

Quick Start

Get notifications running on your site in under 2 minutes.

html<!-- Service Worker (handles browser push) -->
<script
  crossorigin="anonymous"
  src="https://pinglet.enjoys.in/api/v1/public/scripts/v0.0.3/sw.js"
></script>

<!-- Main SDK -->
<script
  type="module"
  crossorigin="anonymous"
  src="https://pinglet.enjoys.in/api/v1/public/libs/pinglet-sse.js"
  data-endpoint="https://pinglet.enjoys.in/api/v1/notifications"
  data-configured-domain="yourdomain.com"
  data-project-id="YOUR_PROJECT_ID"
  data-pinglet-id="YOUR_PINGLET_ID"
  data-checksum="sha384-XXXXXXX"
></script>

bashcurl -X POST https://pinglet.enjoys.in/api/v1/notifications/send \
  -H "Content-Type: application/json" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -d '{
    "project_id": "YOUR_PROJECT_ID",
    "type": 0,
    "variant": "default",
    "body": {
      "title": "Hello from Pinglet!",
      "description": "Your first notification"
    }
  }'

Script Tag Attributes

Reference for all data-* attributes on the SDK script tag.

Notification Types

Pinglet supports 4 notification types. Each type uses the same API endpoint but with different payloads.

jsonPOST /api/v1/notifications/send

{
  "projectId": "your-project-id",
  "type": "0",
  "body": {
    "title": "New Message",
    "description": "You have 3 unread messages",
    "icon": "🔔",
    "logo": "https://cdn.example.com/logo.png",
    "url": "https://example.com/inbox",
    "media": { "type": "image", "src": "https://cdn.example.com/banner.jpg" },
    "buttons": [
      { "text": "View", "action": "redirect", "src": "https://..." },
      { "text": "Dismiss", "action": "close" }
    ]
  }
}

json// Minimal
{ "projectId": "...", "type": "0", "body": { "title": "Hello!" } }

// With icon + description
{
  "projectId": "...", "type": "0",
  "body": { "title": "Order #123", "description": "Ready for pickup", "icon": "📦" }
}

// With image media
{
  "projectId": "...", "type": "0",
  "body": { "title": "Sale!", "media": { "type": "image", "src": "https://..." } }
}

Glassmorphism (Backward Compatible)

Type 2 is a backward compatible alias — in v0.0.3, it renders identically to Type 0 via showHtmlNotification(). Use Type 0 for new integrations. Existing Type 2 payloads will continue to work.

jsonPOST /api/v1/notifications/send

{
  "projectId": "your-project-id",
  "type": "2",
  "body": {
    "title": "Flash Sale 🔥",
    "description": "50% off all items.",
    "icon": "https://cdn.example.com/icon.png",
    "url": "https://example.com/sale",
    "media": { "type": "image", "src": "https://cdn.example.com/hero.jpg" },
    "buttons": [
      { "text": "Shop", "action": "redirect", "src": "https://..." },
      { "text": "Track", "action": "event", "event": "sale:click", "data": {} },
      { "text": "Close", "action": "close" }
    ]
  }
}

json// Minimal
{ "projectId": "...", "type": "2", "body": { "title": "Welcome!" } }

// Full
{
  "projectId": "...", "type": "2",
  "body": {
    "title": "Payment Received",
    "description": "$99.00 from [email protected]",
    "icon": "https://cdn.example.com/avatar.png",
    "buttons": [
      { "text": "View", "action": "redirect", "src": "https://..." },
      { "text": "Close", "action": "close" }
    ]
  }
}

Browser Push Notification

Notifications delivered via Web Push API → Service Worker → native OS notification. Reaches users even when the tab is closed. Requires user's push permission grant.

jsonPOST /api/v1/notifications/send

{
  "projectId": "your-project-id",
  "type": "-1",
  "data": {
    "title": "Order Shipped",
    "body": "Your package is on the way.",
    "icon": "https://cdn.example.com/icon.png",
    "badge": "https://cdn.example.com/badge.png",
    "image": "https://cdn.example.com/hero.jpg",
    "tag": "order-123",
    "requireInteraction": true,
    "silent": false,
    "renotify": false,
    "dir": "ltr",
    "timestamp": 1711000000000,
    "vibrate": [200, 100, 200],
    "data": {
      "url": "https://example.com/track/123",
      "duration": 5000
    },
    "actions": [
      { "action": "view", "title": "View Order", "icon": "..." },
      { "action": "dismiss", "title": "Dismiss" }
    ]
  }
}

Custom Template Notification

Server-stored templates created in the dashboard. Pass data to fill template placeholders. Useful for consistent, reusable notification formats.

jsonPOST /api/v1/notifications/send

{
  "projectId": "your-project-id",
  "type": "1",
  "template_id": "42",
  "custom_template": {
    "user_name": "John Doe",
    "order_total": "$49.99",
    "action_url": "https://example.com/orders/123",
    "product_image": "https://cdn.example.com/product.jpg"
  }
}

API Reference

Send notifications via the Pinglet REST API. Rate limit: 30 requests/minute.

json{
  "Content-Type": "application/json",
  "X-Project-ID": "your-project-id",
  "X-Pinglet-Version": "1.0.5"
}

Payload Schemas

Request body schemas for each notification type.

json{
  "x-project-id": "your-project-id",
  "x-pinglet-version": "1.0.5"
}

json{
  "project_id": "your-project-id",
  "type": 0,
  "variant": "default",
  "body": {
    "title": "Hello from Pinglet",
    "description": "New design incoming!",
    "media": {
      "type": "icon",
      "src": "🔥"
    },
    "buttons": [
      {
        "text": "Fix Now",
        "action": "link",
        "src": "https://example.com/action"
      },
      {
        "text": "Dismiss",
        "action": "close"
      }
    ]
  },
  "overrides": {
    "auto_dismiss": false
  }
}

json{
  "message": "OK",
  "result": "Notification Sent",
  "success": true,
  "X-API-PLATFORM STATUS": "OK"
}

Custom Events

Trigger real DOM CustomEvents on the user's browser when they click a notification button. Your frontend JavaScript listens for the event and executes any logic — add to cart, open modal, track conversion, and more.

json{
  "type": "2",
  "projectId": "your-project-id",
  "body": {
    "title": "Flash Sale!",
    "description": "50% off — limited time only",
    "buttons": [
      {
        "text": "Add to Cart",
        "action": "event",
        "event": "pinglet:addToCart",
        "data": {
          "productId": "SKU-123",
          "quantity": 1
        }
      },
      {
        "text": "Maybe Later",
        "action": "close"
      }
    ]
  }
}

html<script>
  window.addEventListener("pinglet:addToCart", function (e) {
    console.log("Payload:", e.detail);
    addItemToCart(e.detail.productId, e.detail.quantity);
  });
</script>

tsxuseEffect(() => {
  const handler = (e: CustomEvent) => {
    console.log("Event data:", e.detail);
  };
  window.addEventListener("pinglet:addToCart", handler);
  return () => window.removeEventListener("pinglet:addToCart", handler);
}, []);

Button Actions Reference

Overrides & Config

Customize notification appearance and behavior per-request using the overrides object.

Full API Schema Reference

Top-level schema for POST /api/v1/notifications/send. Rate limit: 30 req/min.

json{
  "projectId":       "string (exactly 24 chars)",   // REQUIRED
  "type":            ""-1" | "0" | "1" | "2"",       // REQUIRED
  "variant":         "string",                      // optional (type 0 only)
  "tag":             "string",                      // optional
  "overrides":       "OverridesObject",              // optional (premium only)
  "body":            "BodyObject",                   // required for type 0 & 2
  "data":            "BrowserPushObject",             // required for type -1
  "custom_template": "Record<string, any>",          // required for type 1
  "template_id":     "string"                        // required for type 1
}

json{
  "title":       "string (min 3 chars)",  // REQUIRED
  "description": "string",
  "icon":        "string",               // emoji/base64 (type 0), URL (type 2)
  "logo":        "string",               // type 0 only
  "url":         "string (valid URL)",
  "media":       { "type": "image|video|audio|iframe", "src": "url" },
  "buttons":     "ButtonSchema[] (max 3)"
}

json// redirect / link
{ "text": "View", "action": "redirect", "src": "https://..." }

// reload / close
{ "text": "Refresh", "action": "reload" }
{ "text": "Dismiss", "action": "close" }

// alert
{ "text": "Alert", "action": "alert", "src": "Message text" }

// event
{ "text": "Track", "action": "event", "event": "my-event", "data": {} }

// onClick (advanced)
{ "text": "Run", "action": "onClick", "onClick": "() => ..." }

Global Config

When the SDK initializes, it fetches project config from the server. These settings are merged with SDK defaults. Premium overrides are applied per-notification.

jsonGET {endpoint}/load/projects?projectId=xxx&domain=yyy

Response:
{
  "success": true,
  "result": {
    "is_premium": false,
    "config": {
      "position": "bottom-left",
      "transition": "fade",
      "duration": 5000,
      "maxVisible": 3,
      "stacking": true,
      "auto_dismiss": true,
      "dismissible": true,
      "website": true,
      "favicon": true,
      "time": true,
      "sound": { "play": false, "src": "", "volume": 0.5 },
      "theme": { "mode": "auto" },
      "branding": { "show": true, "once": true, "html": "" },
      "progressBar": { "show": true, "color": "" }
    },
    "template": { "config": { ... } }
  }
}

SSE Connection & Lifecycle

The SDK uses Server-Sent Events for real-time notification delivery.

bash// SSE endpoint
GET /api/v1/notifications/sse?projectId=xxx&pingletId=yyy

Stacking & Queue Behavior

Branding

Branding appears as a footer on all glassmorphism notifications (Type 0, 1, & 2).

json// Custom branding (via overrides or dashboard config)
{
  "branding": {
    "show": true,
    "html": "Powered by <b>Enjoys</b> 🚀"
  }
}

Dark Mode

The SDK supports 3 theme modes.

Font & Image Caching

Error Handling

Notes & Gotchas