Android

Overview

The siren-android-inbox SDK is a comprehensive and customizable Android UI kit for displaying and managing notifications. This documentation provides comprehensive information on how to install, configure, and use the SDK effectively.

Installation

Prerequisites

Android Studio Arctic Fox or later
Android SDK 21 or higher
Kotlin 1.5.0 or higher

Add JitPack Repository

Add the JitPack repository to your project-level build.gradle file:

allprojects {
    repositories {
        // ...
        maven { url 'https://jitpack.io' }
    }
}

Add Dependency

Add the SDK dependency to your app-level build.gradle file:

dependencies {
    implementation 'com.github.KeyValueSoftwareSystems:siren-android-inbox:1.0.1'
}

Configuration

Initialization

Initialize SirenSDK in your MainActivity by passing the context, token, recipientId, and error callback:

import com.keyvalue.siren.androidsdk.helper.client.SirenSDK

class MainActivity : AppCompatActivity() {
    private lateinit var sirenSDK: SirenSDK

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        sirenSDK = SirenSDK.getInstance(
            context = applicationContext,
            token = "YOUR_USER_TOKEN",
            recipientId = "YOUR_RECIPIENT_ID",
            object : ErrorCallback {
                override fun onError(jsonObject: JSONObject) {
                    // Handle initialization error
                }
            }
        )
    }
}

Configure Notification Icon

Add a notification icon with a badge showing unread count:

import com.keyvalue.siren.androidsdk.helper.customization.SirenInboxIconProps

sirenSDK.SirenInboxIcon(
    SirenInboxIconProps(
        theme = customTheme,  // Optional: Custom theme
        darkMode = true,      // Optional: Enable dark mode
        notificationIcon = CustomIcon(),  // Optional: Custom icon
    ),
    object : SirenInboxIconCallback {
        override fun onError(jsonObject: JSONObject) {
            // Handle error
        }

        override fun onClick() {
            // Handle icon click
        }
    },
)

Notification Icon Parameters

Parameter	Description	Type	Default
`theme`	Theme configuration	`Theme`	`null`
`customStyles`	Custom styles	`CustomStyles`	`null`
`notificationIcon`	Custom notification icon	`@Composable (() -> Unit)?`	`null`
`darkMode`	Enable dark mode	`Boolean`	`false`
`disabled`	Disable click on icon	`Boolean`	`false`
`hideBadge`	Hide the badge on icon	`Boolean`	`false`

Configure Notification Inbox

Display a paginated list of notifications:

import com.keyvalue.siren.androidsdk.helper.customization.SirenInboxProps

sirenSDK.SirenInbox(
    SirenInboxProps(
        title = "My Notifications",
        darkMode = true,
        hideHeader = false,
        // Other customization options...
    ),
    object : SirenInboxCallback {
        override fun onCardClick(notificationItem: AllNotificationResponseData) {
            // Handle notification click
        }

        override fun onError(jsonObject: JSONObject) {
            // Handle error
        }
    }
)

Inbox Parameters

Parameter	Description	Type	Default
`theme`	Theme configuration	`Theme`	`null`
`title`	Inbox title	`String`	”Notifications”
`hideHeader`	Hide header section	`Boolean`	`false`
`hideClearAll`	Hide clear all button	`Boolean`	`false`
`darkMode`	Enable dark mode	`Boolean`	`false`
`cardProps`	Notification card props	`CardProps`	`null`
`listEmptyComponent`	Custom empty state	`@Composable () -> Unit`	`null`
`customHeader`	Custom header component	`@Composable () -> Unit`	`null`
`customFooter`	Custom footer component	`@Composable () -> Unit`	`null`
`customNotificationCard`	Custom card component	`@Composable (AllNotificationResponseData) -> Unit`	`null`
`customLoader`	Custom loading component	`@Composable () -> Unit`	`null`
`customErrorWindow`	Custom error component	`@Composable () -> Unit`	`null`
`itemsPerFetch`	Items per API request (max 50)	`Int`	`20`

Customization

Theme Customization

import androidx.compose.ui.graphics.Color

val customTheme = Theme(
    light = ThemeProps(
        colors = ThemeColors(
            primaryColor = Color(0xFF6200EE),
            textColor = Color(0xFF000000),
            // ... other colors
        ),
        badgeStyle = BadgeThemeProps(
            color = Color.Red,
            textColor = Color.White
        )
        // ... other theme props
    ),
    dark = ThemeProps(
        // Dark theme overrides
    )
)

Style Customization

import androidx.compose.ui.unit.dp
import androidx.compose.ui.text.font.FontWeight

val customStyles = CustomStyles(
    notificationIcon = NotificationIconStyle(
        size = 48.dp
    ),
    windowHeader = WindowHeaderStyle(
        height = 56.dp,
        titleFontWeight = FontWeight.Bold,
        titleSize = 18.sp
    )
    // ... other style customizations
)

Functions

Notification Management

// Mark notifications as read by date
sirenSDK.markNotificationsAsReadByDate(
    startDate = "2023-01-01T00:00:00Z",
    callback = object : SirenAllNotificationUpdateCallback {
        override fun onSuccess(dataStatus: DataStatus?) {
            // Handle success
        }
        override fun onError(jsonObject: JSONObject) {
            // Handle error
        }
    }
)

// Mark single notification as read
sirenSDK.markAsRead(
    notificationId = "123",
    callback = object : MarkAsReadByIdCallback {
        override fun onSuccess(responseData: MarkAsReadByIdResponseData?) {
            // Handle success
        }
        override fun onError(jsonObject: JSONObject) {
            // Handle error
        }
    }
)

// Delete notification
sirenSDK.deleteNotification(
    notificationId = "123",
    callback = object : SirenAllNotificationUpdateCallback {
        override fun onSuccess(dataStatus: DataStatus?) {
            // Handle success
        }
        override fun onError(jsonObject: JSONObject) {
            // Handle error
        }
    }
)

// Update user token
sirenSDK.updateToken(
    userToken = "NEW_USER_TOKEN",
    recipientId = "NEW_RECIPIENT_ID"
)

Error Codes

Error Code	Description
`TIMED_OUT`	Request timed out
`INVALID_TOKEN`	The token passed is invalid
`INVALID_RECIPIENT_ID`	The recipient ID is invalid
`TOKEN_VERIFICATION_FAILED`	Token verification failed
`GENERIC_API_ERROR`	Unexpected API error

Example

class MainActivity : AppCompatActivity() {
    private lateinit var sirenSDK: SirenSDK

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Initialize SDK
        sirenSDK = SirenSDK.getInstance(
            context = applicationContext,
            token = "YOUR_USER_TOKEN",
            recipientId = "YOUR_RECIPIENT_ID",
            object : ErrorCallback {
                override fun onError(jsonObject: JSONObject) {
                    Log.e("SirenSDK", "Initialization error: ${jsonObject.toString()}")
                }
            }
        )

        // Set up notification icon
        setContent {
            sirenSDK.SirenInboxIcon(
                SirenInboxIconProps(
                    darkMode = isSystemInDarkTheme(),
                    notificationIcon = {
                        Icon(
                            imageVector = Icons.Default.Notifications,
                            contentDescription = "Notifications",
                            modifier = Modifier.size(24.dp)
                        )
                    }
                ),
                object : SirenInboxIconCallback {
                    override fun onError(jsonObject: JSONObject) {
                        Log.e("SirenSDK", "Icon error: ${jsonObject.toString()}")
                    }

                    override fun onClick() {
                        // Show notifications list
                        showInbox()
                    }
                }
            )
        }
    }

    private fun showInbox() {
        // Show notifications list in a dialog or new screen
        setContent {
            sirenSDK.SirenInbox(
                SirenInboxProps(
                    title = "My Notifications",
                    darkMode = isSystemInDarkTheme()
                ),
                object : SirenInboxCallback {
                    override fun onCardClick(notificationItem: AllNotificationResponseData) {
                        // Handle notification click
                        Toast.makeText(
                            this@MainActivity,
                            "Clicked: ${notificationItem.title}",
                            Toast.LENGTH_SHORT
                        ).show()
                    }

                    override fun onError(jsonObject: JSONObject) {
                        Log.e("SirenSDK", "Inbox error: ${jsonObject.toString()}")
                    }
                }
            )
        }
    }
}

Backend SDKs

Frontend SDKs

Overview

Installation

Prerequisites

Add JitPack Repository

Add Dependency

Configuration

Initialization

Configure Notification Icon

Notification Icon Parameters

Configure Notification Inbox

Inbox Parameters

Customization

Functions

Error Codes

Example

​Overview

​Installation

​Prerequisites

​Add JitPack Repository

​Add Dependency

​Configuration

​Initialization

​Configure Notification Icon

​Notification Icon Parameters

​Configure Notification Inbox

​Inbox Parameters

​Customization

​

​Functions

​Error Codes

​Example

Overview

Installation

Prerequisites

Add JitPack Repository

Add Dependency

Configuration

Initialization

Configure Notification Icon

Notification Icon Parameters

Configure Notification Inbox

Inbox Parameters

Customization

Functions

Error Codes

Example