IronNotify SDK for Java

Event notifications and alerts SDK for Java applications. Send notifications, receive real-time updates, and manage notification state.

Installation

Maven

<dependency>
    <groupId>com.ironservices</groupId>
    <artifactId>notify</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'com.ironservices:notify:1.0.0'

Quick Start

Send a Simple Notification

import com.ironservices.notify.*;
import java.util.Map;

public class Main {
    public static void main(String[] args) {
        // Initialize
        IronNotify.init("ak_live_xxxxx");

        // Send a simple notification
        SendResult result = IronNotify.notify(
            "order.created",
            "New Order Received",
            "Order #1234 has been placed",
            SeverityLevel.SUCCESS,
            Map.of("order_id", "1234", "amount", 99.99)
        );

        if (result.isSuccess()) {
            System.out.println("Notification sent: " + result.getNotificationId());
        }

        // Shutdown when done
        IronNotify.shutdown();
    }
}

Fluent Event Builder

import com.ironservices.notify.*;
import java.time.Duration;

public class Main {
    public static void main(String[] args) {
        IronNotify.init("ak_live_xxxxx");

        // Build complex notifications with the fluent API
        SendResult result = IronNotify.event("payment.failed")
            .withTitle("Payment Failed")
            .withMessage("Payment could not be processed")
            .withSeverity(SeverityLevel.ERROR)
            .withMetadata("order_id", "1234")
            .withMetadata("reason", "Card declined")
            .withAction("Retry Payment", "/orders/1234/retry", null, "primary")
            .withAction(EventBuilder.action("Contact Support")
                .handler("open_support")
                .build())
            .forUser("user-123")
            .withDeduplicationKey("payment-failed-1234")
            .expiresIn(Duration.ofHours(24))
            .send();

        if (result.isQueued()) {
            System.out.println("Notification queued for later");
        }

        IronNotify.shutdown();
    }
}

Async Support

import com.ironservices.notify.*;
import java.util.concurrent.CompletableFuture;

public class Main {
    public static void main(String[] args) {
        IronNotify.init("ak_live_xxxxx");

        // Async notification
        CompletableFuture<SendResult> future = IronNotify.notifyAsync(
            "user.signup",
            "New User Registered"
        );

        future.thenAccept(result -> {
            System.out.println("Notification sent: " + result.isSuccess());
        });

        // Async event builder
        IronNotify.event("order.shipped")
            .withTitle("Order Shipped")
            .forUser("user-123")
            .sendAsync()
            .thenAccept(result -> System.out.println("Done!"));

        // Wait for async operations
        future.join();
        IronNotify.shutdown();
    }
}

Using the Client Directly

import com.ironservices.notify.*;

public class Main {
    public static void main(String[] args) {
        NotifyClient client = new NotifyClient(
            NotifyOptions.builder()
                .apiKey("ak_live_xxxxx")
                .debug(true)
                .build()
        );

        // Send notification
        SendResult result = client.notify("event.type", "Title");

        // Use event builder
        result = client.event("event.type")
            .withTitle("Title")
            .send();

        // Clean up
        client.close();
    }
}

Configuration

import com.ironservices.notify.*;
import java.time.Duration;

NotifyClient client = new NotifyClient(
    NotifyOptions.builder()
        .apiKey("ak_live_xxxxx")
        .apiBaseUrl("https://api.ironnotify.com")
        .webSocketUrl("wss://ws.ironnotify.com")
        .debug(false)
        .enableOfflineQueue(true)
        .maxOfflineQueueSize(100)
        .autoReconnect(true)
        .maxReconnectAttempts(5)
        .reconnectDelay(Duration.ofSeconds(1))
        .httpTimeout(Duration.ofSeconds(30))
        .build()
);

Configuration Options

Option	Type	Default	Description
apiKey	String	required	Your API key (ak_live_xxx or ak_test_xxx)
apiBaseUrl	String	https://api.ironnotify.com	API base URL
webSocketUrl	String	wss://ws.ironnotify.com	WebSocket URL
debug	boolean	false	Enable debug logging
enableOfflineQueue	boolean	true	Queue notifications when offline
maxOfflineQueueSize	int	100	Max offline queue size
autoReconnect	boolean	true	Auto-reconnect WebSocket
maxReconnectAttempts	int	5	Max reconnection attempts
reconnectDelay	Duration	1s	Base reconnection delay
httpTimeout	Duration	30s	HTTP request timeout

Severity Levels

SeverityLevel.INFO     // "info"
SeverityLevel.SUCCESS  // "success"
SeverityLevel.WARNING  // "warning"
SeverityLevel.ERROR    // "error"
SeverityLevel.CRITICAL // "critical"

Actions

// Simple action with URL
IronNotify.event("order.shipped")
    .withTitle("Order Shipped")
    .withAction("Track Package", "https://tracking.example.com/123")
    .send();

// Action with handler
IronNotify.event("order.shipped")
    .withTitle("Order Shipped")
    .withAction("View Order", null, "view_order", "default")
    .send();

// Using action builder
IronNotify.event("order.shipped")
    .withTitle("Order Shipped")
    .withAction(EventBuilder.action("Track Package")
        .url("https://tracking.example.com/123")
        .style("primary")
        .build())
    .send();

Deduplication

Prevent duplicate notifications:

IronNotify.event("reminder")
    .withTitle("Daily Reminder")
    .withDeduplicationKey("daily-reminder-2024-01-15")
    .send();

Grouping

Group related notifications:

IronNotify.event("comment.new")
    .withTitle("New Comment")
    .withGroupKey("post-123-comments")
    .send();

Expiration

import java.time.Duration;
import java.time.Instant;

// Expires in 1 hour
IronNotify.event("flash_sale")
    .withTitle("Flash Sale!")
    .expiresIn(Duration.ofHours(1))
    .send();

// Expires at specific time
IronNotify.event("event_reminder")
    .withTitle("Event Tomorrow")
    .expiresAt(Instant.now().plus(Duration.ofDays(1)))
    .send();

Managing Notifications

Get Notifications

import java.util.List;
import java.io.IOException;

// Get all notifications
List<Notification> notifications = client.getNotifications();

// With options
List<Notification> unread = client.getNotifications(10, 0, true);

// Async
client.getNotificationsAsync(10, 0, false)
    .thenAccept(list -> System.out.println("Got " + list.size() + " notifications"));

Mark as Read

// Mark single notification
client.markAsRead("notification-id");

// Mark all as read
client.markAllAsRead();

Get Unread Count

int count = client.getUnreadCount();
System.out.printf("You have %d unread notifications%n", count);

Real-Time Notifications

NotifyClient client = new NotifyClient(new NotifyOptions("ak_live_xxxxx"));

client.onNotification(notification -> {
    System.out.println("New notification: " + notification.getTitle());
});

client.onUnreadCountChange(count -> {
    System.out.println("Unread count: " + count);
});

client.onConnectionStateChange(state -> {
    System.out.println("Connection state: " + state);
});

client.connect();
client.subscribeToUser("user-123");
client.subscribeToApp();

Offline Support

Notifications are automatically queued when offline:

// This will be queued if offline
IronNotify.notify("event", "Title");

// Manually flush the queue
IronNotify.flush();

// Or async
IronNotify.flushAsync().join();

Requirements

• Java 11+
• OkHttp 4.x
• Gson 2.x

Thread Safety

The client is thread-safe and can be used from multiple threads concurrently.

Links

• Documentation
• Dashboard

License

MIT License - see LICENSE for details.