Siren Android Inbox

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.

1. Installation

You will need your sdk token for initializing your library.

1. Add the JitPack repository to your build file

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

2. Add the dependency

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

2. Configuration

2.1 Initialization

Initialize SirenSDK in MainActivity by passing the context, token, recipientId and errorCallback

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

class MainActivity {
    ...

    val sirenSDK =
        SirenSDK.getInstance(
            context = applicationContext,
            token = "USER_TOKEN",
            recipientId = "RECIPIENT_ID",
            object : ErrorCallback {
                override fun onError(jsonObject: JSONObject) {
                }
            },
        )
    ...
}

2.2 Configure notification icon

This composable function consists of a notification icon along with a badge to display the number of unviewed notifications.

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

sirenSDK.SirenInboxIcon(
    SirenInboxIconProps(
        theme = customTheme,
        darkMode = true,
        customStyles = customStyles,
        notificationIcon = CustomIcon(),
    ),
    object : SirenInboxIconCallback {
        override fun onError(jsonObject: JSONObject) {
        }

        override fun onClick() {
        }
    },
)

Parameters for notification icon

Below are optional parameters available for the icon composable function:

Parameter	Description	Type	Default value
theme	Data class defining the theme configuration	Theme	null
customStyles	Data class defining the customizable styles	CustomStyles	null
notificationIcon	Option to use custom notification icon	@Composable (() -> Unit)?	null
darkMode	Toggle to enable dark mode	Boolean	false
disabled	Toggle to disable click on icon	Boolean	false
hideBadge	Toggle to hide the badge displayed on the notification icon	Boolean	false

2.3 Configure notification inbox

Inbox is a paginated list view for displaying notifications.

import com.keyvalue.siren.androidsdk.helper.customization.SirenInboxProps
import com.keyvalue.siren.androidsdk.data.model.AllNotificationResponseData

sirenSDK.SirenInbox(
    SirenInboxProps(
        theme = customTheme,
        title = "Notifications",
        hideHeader = false,
        darkMode = true,
    ),
    object : SirenInboxCallback {
        override fun onCardClick(notificationItem: AllNotificationResponseData) {
        }

        override fun onError(jsonObject: JSONObject) {
        }
    },
)

Siren Inbox parameters

Given below are the list of parameters of the Siren inbox composable function:

Parameter	Description	Type	Default value
theme	Data class defining the theme configuration	Theme	null
customStyles	Data class defining the customizable styles	Theme	null
title	Title of the notification inbox	String	"Notifications"
hideHeader	Toggle to hide the header section	Boolean	false
hideClearAll	Toggle to hide the clear all button	Boolean	false
darkMode	Toggle to enable dark mode	Boolean	false
cardProps	Props for customizing the notification cards	CardProps	null
listEmptyComponent	Custom composable function for empty notification list	(@Composable () -> Unit)	null
customHeader	Custom header composable function	(@Composable () -> Unit)	null
customFooter	Custom footer composable function	(@Composable () -> Unit)	null
customNotificationCard	Custom click handler for notification cards	(@Composable (AllNotificationResponseData) -> Unit)	null
customLoader	Custom composable function to display the initial loading state	(@Composable () -> Unit)	null
customErrorWindow	Custom error window	(@Composable () -> Unit)	null
itemsPerFetch	Number of notifications fetch per api request (have a max cap of 50)	Int	20

CardProps

data class CardProps(
    val hideAvatar: Boolean? = false,
)

Theme customization

Here are the available theme options:

import androidx.compose.ui.graphics.Color

data class Theme(
    val dark: ThemeProps? = null,
    val light: ThemeProps? = null,
)

data class ThemeProps(
    val colors: ThemeColors? = null,
    val badgeStyle: BadgeThemeProps? = null,
    val windowHeader: WindowHeaderThemeProps? = null,
    val windowContainer: WindowContainerThemeProps? = null,
    val notificationCard: NotificationCardThemeProps? = null,
)

data class ThemeColors(
    val primaryColor: Color? = null,
    val textColor: Color? = null,
    val neutralColor: Color? = null,
    val borderColor: Color? = null,
    val highlightedCardColor: Color? = null,
    val dateColor: Color? = null,
    val deleteIcon: Color? = null,
    val timerIcon: Color? = null,
    val clearAllIcon: Color? = null,
    val infiniteLoader: Color? = null,
)

data class BadgeThemeProps(
    val color: Color? = null,
    val textColor: Color? = null,
)

data class WindowHeaderThemeProps(
    val background: Color? = null,
    val titleColor: Color? = null,
    val headerActionColor: Color? = null,
    val borderColor: Color? = null,
)

data class WindowContainerThemeProps(
    val background: Color? = null,
)

data class NotificationCardThemeProps(
    val borderColor: Color? = null,
    val background: Color? = null,
    val titleColor: Color? = null,
    val descriptionColor: Color? = null,
)

Style options

Here are the custom style options:

import androidx.compose.ui.unit.Dp
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.TextUnit
import androidx.compose.ui.graphics.Shape

data class CustomStyles(
    val notificationIcon: NotificationIconStyle? = null,
    val window: WindowStyle? = null,
    val windowHeader: WindowHeaderStyle? = null,
    val windowContainer: WindowContainerStyle? = null,
    val notificationCard: NotificationCardStyle? = null,
    val badgeStyle: BadgeStyle? = null,
    val deleteIcon: DeleteIconStyle? = null,
    val dateIcon: DateIconStyle? = null,
    val clearAllIcon: ClearAllIconStyle? = null,
)

data class NotificationIconStyle(
    val size: Dp? = null,
)

data class WindowStyle(
    val width: Dp? = null,
    val height: Dp? = null,
)

data class WindowHeaderStyle(
    val height: Dp? = null,
    val titleFontWeight: FontWeight? = null,
    val titleSize: TextUnit? = null,
    val closeIconSize: Dp? = null,
    val titlePadding: Dp? = null,
)

data class WindowContainerStyle(
    val padding: Dp? = null,
)

data class NotificationCardStyle(
    val padding: Dp? = null,
    val borderWidth: Dp? = null,
    val avatarSize: Dp? = null,
    val titleFontWeight: FontWeight? = null,
    val titleSize: TextUnit? = null,
    val descriptionSize: TextUnit? = null,
    val dateSize: TextUnit? = null,
)

data class BadgeStyle(
    val size: Dp? = null,
    val textSize: TextUnit? = null,
    val borderShape: Shape? = null,
    val top: Int? = null,
    val right: Int? = null,
)

data class DeleteIconStyle(
    val size: Dp? = null,
)

data class DateIconStyle(
    val size: Dp? = null,
)

data class ClearAllIconStyle(
    val size: Dp? = null,
)

3. Functions

Utility functions for modifying notifications:

Functions	Parameters	Type	Description
markNotificationsAsReadByDate	startDate	ISO date string	Sets the read status of notifications to true until the given date
markAsRead	id	string	Set read status of a notification to true
deleteNotification	id	string	Delete a notification by id
deleteNotificationsByDate	startDate	ISO date string	Delete all notifications until given date
markNotificationsAsViewed	startDate	ISO date string	Sets the viewed status of notifications to true until the given date
updateToken	userToken, recipientId	string	To change the tokens

Sample code:

import com.keyvalue.siren.androidsdk.helper.client.SirenSDK
import com.keyvalue.siren.androidsdk.helper.client.callbacks.ErrorCallback
import com.keyvalue.siren.androidsdk.data.model.MarkAsReadByIdResponseData
import com.keyvalue.siren.androidsdk.helper.client.callbacks.MarkAsReadByIdCallback
...
    val sirenSDK =
        SirenSDK.getInstance(
            this,
            "userToken",
            "recipientId",
            object : ErrorCallback {
                override fun onError(jsonObject: JSONObject) {
                }
            },
        )
    fun markAsRead() {
        sirenSDK.markAsRead(
            notificationId = "notificationId",
            callback = object : MarkAsReadByIdCallback {
                override fun onSuccess(responseData: MarkAsReadByIdResponseData?) {
                    // onSuccess
                }
                override fun onError(jsonObject: JSONObject) {
                    // onError
                }
            }
        )
    }

4. Error codes

Given below are all possible error codes thrown by sdk.

Error code	Description
TIMED_OUT	Request timed out
INVALID_TOKEN	The token passed is invalid
INVALID_RECIPIENT_ID	The recipient id passed is invalid
TOKEN_VERIFICATION_FAILED	Verification of the given tokens has failed
GENERIC_API_ERROR	Occurrence of an unexpected api error

Example

Here's a basic example to help you get started

package com.keyvalue.sirensampleapp

// Add all necessary imports
...
import com.keyvalue.siren.androidsdk.data.model.AllNotificationResponseData
import com.keyvalue.siren.androidsdk.data.model.DataStatus
import com.keyvalue.siren.androidsdk.helper.client.SirenSDK
import com.keyvalue.siren.androidsdk.helper.client.callbacks.ErrorCallback
import com.keyvalue.siren.androidsdk.helper.client.callbacks.SirenAllNotificationUpdateCallback
import com.keyvalue.siren.androidsdk.helper.client.callbacks.SirenInboxCallback
import com.keyvalue.siren.androidsdk.helper.client.callbacks.SirenInboxIconCallback
import com.keyvalue.siren.androidsdk.helper.customization.SirenInboxIconProps
import com.keyvalue.siren.androidsdk.helper.customization.SirenInboxProps

    // replace with userToken and recipientId

    val sirenSDK =
        SirenSDK.getInstance(
            this,
            "userToken",
            "recipientId",
            object : ErrorCallback {
                override fun onError(jsonObject: JSONObject) {
                }
            },
        )
        
    sirenSDK.SirenInboxIcon(
        SirenInboxIconProps(
            darkMode = true,
            notificationIcon = {
                Icon(
                    imageVector = Icons.Default.Notifications,
                    tint = Color(236, 155, 112, 255),
                    modifier = Modifier.size(100.dp),
                )
            },
        ),
        object : SirenInboxIconCallback {
            override fun onError(jsonObject: JSONObject) {
                // onError
            }

            override fun onClick() {
                // onClick
            }
        },
    )

    sirenSDK.SirenInbox(
        SirenInboxProps(),
        object : SirenInboxCallback {
            override fun onCardClick(notificationItem: AllNotificationResponseData) {
                // onClick
            }

            override fun onError(jsonObject: JSONObject) {
                // onError
            }
        },
    )

    fun deleteNotification() {
        sirenSDK.deleteNotification(
            notificationId = "notificationId",
            callback = object : SirenAllNotificationUpdateCallback {
                override fun onSuccess(dataStatus: DataStatus?) {
                    // onSuccess
                }

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

    fun updateToken() {
        sirenSDK.updateToken(
            userToken = "userToken",
            recipientId = "recipientId"
        )
    }