Skip to main content

​
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

ParameterDescriptionTypeDefault
themeTheme configurationThemenull
customStylesCustom stylesCustomStylesnull
notificationIconCustom notification icon@Composable (() -> Unit)?null
darkModeEnable dark modeBooleanfalse
disabledDisable click on iconBooleanfalse
hideBadgeHide the badge on iconBooleanfalse

​
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

ParameterDescriptionTypeDefault
themeTheme configurationThemenull
titleInbox titleString”Notifications”
hideHeaderHide header sectionBooleanfalse
hideClearAllHide clear all buttonBooleanfalse
darkModeEnable dark modeBooleanfalse
cardPropsNotification card propsCardPropsnull
listEmptyComponentCustom empty state@Composable () -> Unitnull
customHeaderCustom header component@Composable () -> Unitnull
customFooterCustom footer component@Composable () -> Unitnull
customNotificationCardCustom card component@Composable (AllNotificationResponseData) -> Unitnull
customLoaderCustom loading component@Composable () -> Unitnull
customErrorWindowCustom error component@Composable () -> Unitnull
itemsPerFetchItems per API request (max 50)Int20

​
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 CodeDescription
TIMED_OUTRequest timed out
INVALID_TOKENThe token passed is invalid
INVALID_RECIPIENT_IDThe recipient ID is invalid
TOKEN_VERIFICATION_FAILEDToken verification failed
GENERIC_API_ERRORUnexpected 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()}")
                    }
                }
            )
        }
    }
}