Welcome to bildirim.live!

Endpoints and Usage

POST /notify?group_id=your_group_id&notification_id=your_notification_id&ttl=seconds
Submit notifications with JSON data. The optional ttl parameter (Time To Live) specifies how long the notification remains valid. If omitted, a default TTL of 1 hour is used.

GET /ws?group_id=your_group_id
Establish a WebSocket connection to receive notifications for the specified group_id.

Description: This service establishes a WebSocket connection to broadcast notifications in real-time to clients connected to a specific group. Notifications are stored with an associated TTL and delivered in JSON format.

Usage Instructions:
1. Embed this iframe in your main page and set the src attribute to: https://bildirim.live?group_id=yourGroupId&origin=parentOrigin.
2. Listen for postMessage events on your main page. Only process messages where messageType equals "notify"; log a warning for any other message types.

Embedding the Invisible Iframe

To embed the notification iframe invisibly into your webpage, include the following HTML snippet:

<iframe class="notification-iframe" src="https://bildirim.live?group_id=yourGroupId&origin=yourParentOrigin"></iframe>

Replace yourGroupId with the specific group identifier and yourParentOrigin with the origin of your main page (e.g., https://yourdomain.com).

Handling postMessage Events in the Parent Page

In order to securely receive notifications from the iframe, add an event listener for message events in your main page. Here is an example of how to implement this:

window.addEventListener('message', function(event) {
    // Validate the origin of the message for security purposes
    if (event.origin !== "https://bildirim.live" && event.origin !== "https://yourdomain.com") {
        console.warn("Received message from untrusted origin:", event.origin);
        return;
    }

    // Check if the message type is 'notify'
    if (event.data && event.data.messageType === "notify") {
        // Process the notification data
        console.log("Received notification:", event.data.messageData);
        // Implement your notification handling logic here
    } else {
        console.warn("Unknown message type received:", event.data);
    }
});

Ensure that you replace https://yourdomain.com with your actual domain. This listener verifies the origin of the message and processes only those messages with messageType set to "notify".

Important: The Role of the origin Parameter

The origin parameter is crucial for secure communication between the iframe and its parent page:

• Security Verification: The server validates incoming WebSocket requests by checking the Origin header. This ensures connections are only accepted from trusted sources such as http://127.0.0.1, https://bildirim.live, or secure subdomains (e.g., https://subdomain.bildirim.live).
• Message Routing: The origin query parameter informs the iframe which parent domain should receive postMessage communications. If the origin parameter is not provided, messages will be sent with the wildcard target ("*"), which is less secure.

Additional Product Features

In addition to the core notification functionality, the system offers several advanced features:

• Group-Based Notification Management: Notifications are organized under a group_id, allowing targeted delivery. Each notification is stored with a TTL and broadcast in real-time to all connected clients.
• Real-Time Notification Broadcasting: When a notification is posted via the POST /notify endpoint, it is immediately sent to all WebSocket clients associated with the relevant group.
• Initial Notification Delivery: On establishing a WebSocket connection, new clients receive any previously stored notifications. If there are no notifications, a "no_notifications" message is sent.
• Automatic Expiration and Cleanup: The system periodically checks for expired notifications and automatically cleans up empty groups to ensure efficient resource usage.
• Concurrent Safety: Internal data structures, including groups and client lists, are protected with mutexes to maintain thread safety during high-concurrency scenarios.