359 lines
8.4 KiB
Markdown
359 lines
8.4 KiB
Markdown
# IronNotify SDK for Java
|
|
|
|
Event notifications and alerts SDK for Java applications. Send notifications, receive real-time updates, and manage notification state.
|
|
|
|
[](https://search.maven.org/artifact/com.ironservices/notify)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
## Installation
|
|
|
|
### Maven
|
|
|
|
```xml
|
|
<dependency>
|
|
<groupId>com.ironservices</groupId>
|
|
<artifactId>notify</artifactId>
|
|
<version>1.0.0</version>
|
|
</dependency>
|
|
```
|
|
|
|
### Gradle
|
|
|
|
```groovy
|
|
implementation 'com.ironservices:notify:1.0.0'
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Send a Simple Notification
|
|
|
|
```java
|
|
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
|
|
|
|
```java
|
|
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
|
|
|
|
```java
|
|
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
|
|
|
|
```java
|
|
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
|
|
|
|
```java
|
|
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
|
|
|
|
```java
|
|
SeverityLevel.INFO // "info"
|
|
SeverityLevel.SUCCESS // "success"
|
|
SeverityLevel.WARNING // "warning"
|
|
SeverityLevel.ERROR // "error"
|
|
SeverityLevel.CRITICAL // "critical"
|
|
```
|
|
|
|
## Actions
|
|
|
|
```java
|
|
// 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:
|
|
|
|
```java
|
|
IronNotify.event("reminder")
|
|
.withTitle("Daily Reminder")
|
|
.withDeduplicationKey("daily-reminder-2024-01-15")
|
|
.send();
|
|
```
|
|
|
|
## Grouping
|
|
|
|
Group related notifications:
|
|
|
|
```java
|
|
IronNotify.event("comment.new")
|
|
.withTitle("New Comment")
|
|
.withGroupKey("post-123-comments")
|
|
.send();
|
|
```
|
|
|
|
## Expiration
|
|
|
|
```java
|
|
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
|
|
|
|
```java
|
|
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
|
|
|
|
```java
|
|
// Mark single notification
|
|
client.markAsRead("notification-id");
|
|
|
|
// Mark all as read
|
|
client.markAllAsRead();
|
|
```
|
|
|
|
### Get Unread Count
|
|
|
|
```java
|
|
int count = client.getUnreadCount();
|
|
System.out.printf("You have %d unread notifications%n", count);
|
|
```
|
|
|
|
## Real-Time Notifications
|
|
|
|
```java
|
|
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:
|
|
|
|
```java
|
|
// 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](https://www.ironnotify.com/docs)
|
|
- [Dashboard](https://www.ironnotify.com)
|
|
|
|
## License
|
|
|
|
MIT License - see [LICENSE](LICENSE) for details.
|