Skip to main content

SDK Setup Guide

Install the SDK​

Octopus is available on Maven Central. Add the dependencies to your build.gradle file:

dependencies {
    // Core SDK functionalities
    implementation("com.octopuscommunity:octopus-sdk:x.x.x")
    // SDK UI Components (optional)
    implementation("com.octopuscommunity:octopus-sdk-ui:x.x.x")
}

See the Octopus SDK GitHub Release section to get the latest published version.

Use the SDK​

As early as possible in your code, you should initialize the OctopusSDK object.

This object is expecting two things:

  • the Octopus Community API key
  • the connection mode

You need to know the app managed fields (also called associated fields) that your community is configured for.

As a reminder, every associated profile field (nickname, picture and/or bio) of your users will be used in the Octopus Community profile of this user. The user will only be able to change it in your profile edition interface and the data will be synced to its community profile.
On the opposite, every dissociated profile fields will only be used as prefilled values during Octopus profile creation. After that, if a user changes its nickname in your app, it won't be reflected in Octopus Community, and the user will be able to change its community nickname in the community part.

At least one app managed field

If your community has at least one associated field, you will have to create the SSO connection mode with the list of the associated fields.

Call the OctopusSDK initialization function in your Application's onCreate() block:

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        
        OctopusSDK.initialize(
            context = this, // Application Context
            apiKey = "YOUR_API_KEY",
            connectionMode = ConnectionMode.SSO(
                // The list of associated fields
                appManagedFields = setOf(ProfileField.NICKNAME, ProfileField.PICTURE)
            )
        )
    }
}

OR

No app managed fields

When there is no app managed fields (i.e. all fields are dissociated), the API is simpler since you only have to configure it in SSO connection mode.

Call the OctopusSDK initialization function in your Application's onCreate() block:

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        
        OctopusSDK.initialize(
            context = this, // Application Context
            apiKey = "YOUR_API_KEY",
            connectionMode = ConnectionMode.SSO()
        )
    }
}

Multi-Community Support​

If your app manages several communities with different API keys, use switchCommunity() to cleanly transition between them at runtime.

The switchCommunity method switches the active community to the one identified by a new API key. It performs a full internal cleanup — flushing pending analytics events, logging out the current user, clearing cached user data and files, and resetting all internal databases — before reinitializing the SDK internals with the new API key. The SDK object reference is preserved; only its internal state is replaced.

warning
  • During the call, you must not call any other Octopus function until switchCommunity finishes.
  • After the call finishes, if you are in SSO mode and have a logged-in user, you must call connectUser again to connect the user to the new community.
  • After the call finishes, you must reconstruct any displayed OctopusHomeScreen.

Parameters:

  • context (Context) — Required. The application context.
  • apiKey (String) — Required. The API key that identifies the new community.
  • connectionMode (ConnectionMode) — Optional. The connection mode for the new community. Default: ConnectionMode.SSO().
// Switch to a new community
OctopusSDK.switchCommunity(
    context = applicationContext,
    apiKey = "NEW_COMMUNITY_API_KEY",
    connectionMode = ConnectionMode.SSO()
)

// After switchCommunity returns, reconnect the user (SSO mode)
OctopusSDK.connectUser(
    ClientUser(
        userId = yourUser.id,
        profile = ClientUser.Profile(
            nickname = yourUser.name,
            bio = yourUser.bio,
            picture = yourUser.picture
        )
    )
) {
    // Fetch asynchronously this user token
    // by calling your /generateOctopusSsoToken route
    getTokenFromServer()
}
tip

switchCommunity() is safe to call even when the SDK is not initialized — it will simply initialize it.

Your application is managing the connection status of the user and inform the Octopus SDK when the user is connected/disconnected

The connectUser API lets you pass the userId. This userId is the string that will identify your user for Octopus. It needs to be unique and always refer to the same user.

You can also pass profile information (nickname, bio, picture). These fields will be used differently depending on whether the field is associated (i.e. in the app managed fields that you provided during SDK initialization) or not:

  • if the field is associated, each time the connectUser function will be called, Octopus will update the field in the user's community profile with the data you provided. Hence, the field in the community profile of the user will always be the same value as in its app profile

  • if the field is not associated, the data you provided will only be used to fill the community profile until the user edits its community profile. Once its done, their community profile remains separate from yours, meaning any updates made to your profile will not be reflected in theirs, and vice versa.

This is why you should call the connectUser function as soon as the user profile changes.

Client User Token​

For security reasons, to ensure that the connected user is legitimate, the API informing the SDK of a user’s connection includes a callback that provides a signed token for authentication. In other words, the SDK will request a token from you when needed to authenticate the user. Therefore, you must add a route like /generateOctopusSsoToken to your backend to generate this token. Follow the Generate a signed JWT for SSO guide for more information

Inform the SDK that your user is connected:

≥ 1.6.0
OctopusSDK.connectUser(
    user = ClientUser(
        userId = yourUserId, // Unique identifier of your user
        profile = ClientUser.Profile(
            nickname = yourUserNickname, // nickname is String?
            bio = yourUserBio, // bio is String?
            picture = yourUserPicture // A Remote URL or a Local Uri
        )
    ),
    tokenProvider = {
        // Fetch asynchronously this user token (suspended callback)
        // by calling your /generateOctopusSsoToken route
    }
)
tip

Check the Community ViewModel Sample for a complete use case.

Deprecated < 1.6.0
OctopusSDK.connectUser(
    user = ClientUser(
        userId = yourUser.id,
        profile = ClientUser.Profile(
            nickname = yourUser.name,
            bio = yourUser.bio,
            picture = yourUser.picture,
            // Age Information:
            // - LegalAgeReached = Your user is more than 16 years old
            // - Underaged = Your user is less than 16 years old
            // - null = You don't know
            ageInformation = AgeInformation.LegalAgeReached
        )
    ),
    tokenProvider = {
        // Return asynchronously this user token (suspended callback)
        // by calling your /generateOctopusSsoToken route
    }
)
  • Inform the SDK that your user is disconnected:
// suspend function — call from a coroutine
OctopusSDK.disconnectUser()
  • Optional: Monitor whether the user is connected to the Octopus platform:
OctopusSDK.isUserConnected

Display the Octopus Community UI​

Now that you have the SDK properly configured, you can add a button in your app that opens the Octopus Community UI.

  1. Add the OctopusHomeContent composable to your community screen.
OctopusTheme(...) { // Customize the Octopus Theme here
    OctopusHomeContent(
        modifier = Modifier.fillMaxSize(),
        navController = navController, // Your main NavHostController
        onNavigateToLogin = {
            // This block will be called when OctopusSDK needs a logged-in user.
            // You should launch your login process here.
            // Example: navController.navigate(LoginRoute)
            // Once the user is logged in, you need to call OctopusSDK.connectUser(...) to link
            // them with Octopus
        },
        // Optional: If your community has at least one associated field:
        onNavigateToProfileEdit = { profileField ->
            // This block will be called when the user tries to modify some fields related
            // to their profile.
            // When this block is called, you should open your profile edition screen.
            // Example: navController.navigate(ProfileScreen(focusNickname = fieldToEdit == ProfileField.NICKNAME))
            // Once the user has edited their profile, you should call OctopusSDK.connectUser(...) to update the Octopus profile.
        }
    )
}
tip

Check the Community Screen Sample for basic usage.

  1. Declare other Octopus sub-screens in your main NavHost:
NavHost(...) { // Your main NavHost
    octopusComposables(
        navController = navController, // Your main NavHostController
        onNavigateToLogin = { ... },
        onNavigateToProfileEdit = { ... }
    ) { backStackEntry, content ->
        // Customize the Octopus Theme possibly based on a specific Octopus Screen here
        OctopusTheme(...) {
            content()
        }
    }
}

This function registers multiple composable() destinations in your NavGraphBuilder for adding the Octopus SDK navigation flow to your app.

tip

Depending on your use case integration mode check the various samples:

Open a specific screen ≥ 1.11.0​

By default, the Octopus UI opens on the main feed. You can also open it directly on a specific screen, such as a post or a group.

Android does not use a single initialScreen parameter — navigation is driven by the standard NavHostController. Two patterns are available depending on the integration mode:

Open in the community context (with back navigation to the main feed)​

If your app integrates the Octopus navigation graph via octopusComposables(navController), use the dedicated navigateToOctopusPost / navigateToOctopusGroup helpers. The user can then navigate back to the main feed naturally.

Open a post:

navController.navigateToOctopusPost(postId = "your-post-id")

Open a group: ≥ 1.11.0

navController.navigateToOctopusGroup(groupId = "your-group-id")

A navigateToOctopusHome() helper is also available to return to the main feed from anywhere.

See the Groups section to retrieve the list of available group ids.

Open a single post or group in isolation (bridge mode)​

When you do not want to integrate the full Octopus navigation graph, use the dedicated public composables in standalone mode. The screen displays a back arrow in the top app bar; tapping it (or using the system back gesture) returns to your app.

Open a post:

OctopusPostDetailsScreen(
    navController = navController,
    postId = "your-post-id"
)

Open a group: ≥ 1.11.0

OctopusGroupDetailsScreen(
    navController = navController,
    groupId = "your-group-id"
)

Both composables also have a Content variant (OctopusPostDetailsContent, OctopusGroupDetailsContent) that exposes navigation callbacks for SSO integration (login, profile edit, URL handling).

Modify bottom safe area​

According to your app, you might want to add a bottom padding to the Octopus UI content.

This can be done by using the contentPadding parameter of the OctopusHomeContent composable.

OctopusHomeContent(
    modifier = Modifier.fillMaxSize(),
    contentPadding = PaddingValues(bottom = 10.dp) // This will add a 10dp padding at the bottom of the Octopus UI
    // ...
)

To see a full example of how you can achieve that, you can check the Floating Bottom Navigation Bar Sample.

Modify the theme​

The Octopus SDK lets you modify its theme so its UI looks more like yours.

You can modify:

  • the colors:

    Please pass colors without any transparency.

    • the primary colors (a main color, a low contrast and a high contrast variations of the main color). If you do not pass a custom value for it, black/white default values will be used.
    • the color of the elements (mostly texts) displayed over the primary color. If you do not pass a custom value for it, white/black default value will be used.

  • the fonts. You can customize the styles (title1, body2, caption1...) used in the sdk. If you do not pass a custom value for it, default value will be used.

  • the logo. This is an image displayed on the Octopus home page and profile creation view. If you do not pass a custom image for it, Octopus logo value will be used.

  • the icons. You can override any icon (or group of icons) used across all SDK screens to match your app's design language. If you do not pass a custom value for it, the SDK's built-in icons will be used.

  • (⚠ Android only) the TopAppBar. You can customize the appearance, title, navigation icons, actions, and colors of the TopAppBar. If you do not pass a custom configuration for it, default TopAppBar will be used.

By default, Octopus will rely on your application's MaterialTheme.colorScheme, but you can customize the UI more precisely by surrounding composables with the OctopusTheme:

To do that, you can override the theme by passing it as an environment object:

octopusComposables(
    navController = navController
) { backStackEntry, content ->
    OctopusTheme(
        colorScheme = if (isSystemInDarkTheme()) {
            octopusDarkColorScheme(
                primary = yourDarkPrimaryColor, // Default: MaterialTheme.colorScheme.primary
                primaryLow = lowContrastVersionOfYourPrimaryColor, // Default: MaterialTheme.colorScheme.primaryContainer
                primaryHigh = highContrastVersionOfYourPrimaryColor, // Default: MaterialTheme.colorScheme.inversePrimary
                onPrimary = yourDarkOnPrimaryColor, // Default: MaterialTheme.colorScheme.onPrimary
                background = yourDarkBackgroundColor // Default: MaterialTheme.colorScheme.background
                // See the complete list in the sources documentation
            )
        } else {
            octopusLightColorScheme(
                primary = yourLightPrimaryColor, // Default: MaterialTheme.colorScheme.primary
                primaryLow = lowContrastVersionOfYourPrimaryColor, // Default: MaterialTheme.colorScheme.primaryContainer
                primaryHigh = highContrastVersionOfYourPrimaryColor, // Default: MaterialTheme.colorScheme.inversePrimary
                onPrimary = yourLightOnPrimaryColor, // Default: MaterialTheme.colorScheme.onPrimary
                background = yourLightBackgroundColor // Default: MaterialTheme.colorScheme.background
                // See the complete list in the sources documentation
            )
        },
        typography = OctopusTypographyDefaults.typography(
            title1 = yourCustomTitle1Style, // Default: TextStyle(fontSize = 26.sp)
            title2 = yourCustomTitle2Style  // Default: TextStyle(fontSize = 22.sp)
            // See the complete list in the sources documentation
        ),
        images = OctopusImagesDefaults.images(
            logo = painterResource(R.drawable.your_custom_logo), // Default: null
            icons = OctopusIconsDefaults.icons(
                // Override any icon or icon group here
            )
        )
        // ... Check the complete parameters list in the sources documentation
    ) {
        content()
    }
}
tip

Use the OctopusThemeGenerator to configure your Community theme with a live preview of the various Octopus screens.

All parameters of the theme have default values. Only override the ones that you want to customize. In the following example, you are creating an OctopusTheme with default colors, default fonts except for the title1, and a custom logo:

OctopusTheme(
    typography = OctopusTypographyDefaults.typography(
        title1 = TextStyle(fontFamily = FontFamily.SansSerif, fontSize = 24.sp)
    ),
    images = OctopusImagesDefaults.images(
        logo = painterResource(R.drawable.your_custom_logo)
    )
) {
    OctopusHomeContent(...)
}

Here is a summary of the impacts of the theme you choose: Light Mode Dark Mode

Here is a summary of the text styles used in the main screens of the SDK: Text Styles

Customize Icons ≥ 1.10.0​

All icons used inside the Octopus Community UI can be replaced with your own assets. Icons will be automatically tinted by the SDK — the colors of your assets will be ignored. Icons should ideally be 24×24 pixels with drawn content of 14.5×14.5 (i.e. 4.75 px transparent border on each side) and square. If your icon is not square, it will be displayed in fit mode and may appear smaller than expected.

If you do not override an icon, the SDK default will be used.

Icons are organized into groups matching different areas of the UI: groups, content (posts, comments, replies, video, polls), profile, gamification, settings, and common (radio buttons, checkboxes, toggles, close, more actions).

warning

As the icons are linked to the UI and the UI can change quite often, this API might change often, some icons won't be used anymore and will be quickly deprecated.

Icons are organized in a hierarchy under OctopusIcons. The structure mirrors the UI areas: groups, content (posts, comments, replies, video, polls), profile, notifications, gamification, and settings. Cross-cutting icons (radio, checkbox, toggle, close, moreActions, report, cellNavIndicator) live at the top level of OctopusIcons directly — Android does not group them under a common namespace.

All icon parameters are optional — only specify the ones you want to change. Pass the custom theme to the SDK by wrapping the Octopus composable in an OctopusTheme:

import com.octopuscommunity.sdk.ui.OctopusIconsDefaults
import com.octopuscommunity.sdk.ui.OctopusImagesDefaults
import com.octopuscommunity.sdk.ui.OctopusTheme

OctopusTheme(
    images = OctopusImagesDefaults.images(
        icons = OctopusIconsDefaults.icons(/* … */)
    )
) {
    OctopusHomeContent(/* … */)
}

Override icons within a specific group​

You can customize only the icons you need. Unspecified parameters keep SDK defaults. For example, to customize some post creation icons:

import com.octopuscommunity.sdk.ui.OctopusIconsDefaults
import com.octopuscommunity.sdk.ui.OctopusImagesDefaults
import com.octopuscommunity.sdk.ui.OctopusTheme

OctopusTheme(
    images = OctopusImagesDefaults.images(
        icons = OctopusIconsDefaults.icons(
            content = OctopusIconsDefaults.content(
                post = OctopusIconsDefaults.post(
                    creation = OctopusIconsDefaults.postCreation(
                        create = painterResource(R.drawable.your_create_post_icon),
                        addPicture = painterResource(R.drawable.your_add_picture_icon),
                        addPoll = painterResource(R.drawable.your_add_poll_icon)
                    )
                )
            )
        )
    )
) {
    OctopusHomeContent(...)
}

Convenience parameters (shared icons)​

Some icons share the same meaning across different parts of the UI (for example, the "report" icon appears in both content and profile contexts). To make it easy to replace all related icons at once, the OctopusIconsDefaults.icons() and OctopusIconsDefaults.content() helpers provide top-level parameters that propagate to nested groups:

  • OctopusIconsDefaults.icons() provides:
    • report → applies to content.report and profile.report
    • close → applies to content.deletePicture (which itself propagates to post.creation.deletePicture, comment.creation.deletePicture and reply.creation.deletePicture)
  • OctopusIconsDefaults.content() provides:
    • notAvailable → applies to post.notAvailable and comment.notAvailable
    • likeNotSelected → applies to post.likeNotSelected, comment.likeNotSelected and reply.likeNotSelected
    • addPicture → applies to post.creation.addPicture, comment.creation.addPicture and reply.creation.addPicture
    • deletePicture → applies to post.creation.deletePicture, comment.creation.deletePicture and reply.creation.deletePicture
    • send → applies to comment.creation.create and reply.creation.create
    • openResponseCreation → applies to post.openCommentCreation and comment.openReplyCreation

Individual icon overrides always take priority over convenience parameters.

Example — replace the report icon everywhere with a single line:

import com.octopuscommunity.sdk.ui.OctopusIconsDefaults
import com.octopuscommunity.sdk.ui.OctopusImagesDefaults
import com.octopuscommunity.sdk.ui.OctopusTheme

OctopusTheme(
    images = OctopusImagesDefaults.images(
        icons = OctopusIconsDefaults.icons(
            report = painterResource(R.drawable.your_custom_report_icon)
        )
    )
) {
    OctopusHomeContent(...)
}

Example — set a default "add picture" icon for all creation forms, but override it specifically for post creation:

import com.octopuscommunity.sdk.ui.OctopusIconsDefaults
import com.octopuscommunity.sdk.ui.OctopusImagesDefaults
import com.octopuscommunity.sdk.ui.OctopusTheme

OctopusTheme(
    images = OctopusImagesDefaults.images(
        icons = OctopusIconsDefaults.icons(
            content = OctopusIconsDefaults.content(
                post = OctopusIconsDefaults.post(
                    creation = OctopusIconsDefaults.postCreation(
                        addPicture = painterResource(R.drawable.my_post_add_picture)
                    )
                ),
                // Applies to comment and reply creation (but not post, since it's overridden above)
                addPicture = painterResource(R.drawable.my_generic_add_picture)
            )
        )
    )
) {
    OctopusHomeContent(...)
}

Customize radio, checkbox, and toggle icons​

By default, the SDK uses native Material3 RadioButton, Checkbox, and Switch widgets. You can replace them with custom icon pairs by providing an OctopusIcons.OnOff instance:

import com.octopuscommunity.sdk.ui.OctopusIcons
import com.octopuscommunity.sdk.ui.OctopusIconsDefaults
import com.octopuscommunity.sdk.ui.OctopusImagesDefaults
import com.octopuscommunity.sdk.ui.OctopusTheme

OctopusTheme(
    images = OctopusImagesDefaults.images(
        icons = OctopusIconsDefaults.icons(
            radio = OctopusIcons.OnOff(
                on = painterResource(R.drawable.your_radio_selected),
                off = painterResource(R.drawable.your_radio_unselected)
            ),
            checkbox = OctopusIcons.OnOff(
                on = painterResource(R.drawable.your_checkbox_checked),
                off = painterResource(R.drawable.your_checkbox_unchecked)
            ),
            toggle = OctopusIcons.OnOff(
                on = painterResource(R.drawable.your_toggle_on),
                off = painterResource(R.drawable.your_toggle_off)
            )
        )
    )
) {
    OctopusHomeContent(...)
}
info

When radio, checkbox, or toggle is null (the default), the native Material3 component is used. Pass an OctopusIcons.OnOff instance to replace it with your custom painters.

Customize reaction images ≥ 1.11.0​

The reaction images displayed on posts, comments, and replies (heart, joy, mouthOpen, clap, cry, rage) can be replaced individually. Like the other icons, all parameters are optional — only specify the ones you want to change, and unspecified ones keep the SDK defaults.

info

Unlike other icons, reaction images are rendered with their original colors — they are not tinted by the SDK. Provide assets that already match your visual identity (color, shading, etc.).

warning

Each replacement image must visually match the meaning of the reaction it represents. The reaction's display name (heart → "Like", joy → "Haha", mouthOpen → "Wow", clap → "Celebrate", cry → "Sad", rage → "Angry") appears as text alongside the image in some surfaces, and is used as the content description read by TalkBack. For example, replacing cry with a party 🎉 image would show a party icon labelled "Sad" — confusing on screen and misleading for accessibility users.

import com.octopuscommunity.sdk.ui.OctopusIconsDefaults
import com.octopuscommunity.sdk.ui.OctopusImagesDefaults
import com.octopuscommunity.sdk.ui.OctopusTheme

OctopusTheme(
    images = OctopusImagesDefaults.images(
        icons = OctopusIconsDefaults.icons(
            content = OctopusIconsDefaults.content(
                reaction = OctopusIconsDefaults.reaction(
                    heart = { painterResource(R.drawable.my_heart_reaction) },
                    joy = { painterResource(R.drawable.my_joy_reaction) },
                    mouthOpen = { painterResource(R.drawable.my_mouth_open_reaction) },
                    clap = { painterResource(R.drawable.my_clap_reaction) },
                    cry = { painterResource(R.drawable.my_cry_reaction) },
                    rage = { painterResource(R.drawable.my_rage_reaction) }
                )
            )
        )
    )
) {
    OctopusHomeContent(...)
}

Full icon customization example​

You can combine all the above into a single OctopusTheme setup:

import com.octopuscommunity.sdk.ui.OctopusIcons
import com.octopuscommunity.sdk.ui.OctopusIconsDefaults
import com.octopuscommunity.sdk.ui.OctopusImagesDefaults
import com.octopuscommunity.sdk.ui.OctopusTheme

OctopusTheme(
    images = OctopusImagesDefaults.images(
        logo = painterResource(R.drawable.your_custom_logo),
        icons = OctopusIconsDefaults.icons(
            close = painterResource(R.drawable.your_close_icon),
            moreActions = painterResource(R.drawable.your_more_actions_icon),
            report = painterResource(R.drawable.your_report_icon),
            content = OctopusIconsDefaults.content(
                addPicture = painterResource(R.drawable.your_add_picture_icon)
            ),
            profile = OctopusIconsDefaults.profile(
                defaultAvatar = painterResource(R.drawable.your_default_avatar)
            ),
            radio = OctopusIcons.OnOff(
                on = painterResource(R.drawable.your_radio_on),
                off = painterResource(R.drawable.your_radio_off)
            ),
            checkbox = OctopusIcons.OnOff(
                on = painterResource(R.drawable.your_checkbox_on),
                off = painterResource(R.drawable.your_checkbox_off)
            ),
            toggle = OctopusIcons.OnOff(
                on = painterResource(R.drawable.your_toggle_on),
                off = painterResource(R.drawable.your_toggle_off)
            )
        )
    )
) {
    OctopusHomeContent(...)
}

Customize the TopAppBar​

You can customize the title displayed in the navigation bar on the main feed screen directly from the OctopusHomeScreen composable. It accepts three parameters for this:

  • titleText: an optional String that overrides the title text shown in the nav bar. When null (default), falls back to the SDK default title (or nothing if a logo is displayed). We highly recommend keeping the text under 18 characters for best results.
  • titleCentered: if true, the title is centered in the nav bar. If false (default), the title is left-aligned (leading).
  • logo: an optional @Composable () -> Painter that provides a custom logo to display in the nav bar. When null (default), the logo from your OctopusTheme is used.

Here is how to display a leading text title:

OctopusHomeScreen(
    navController = navController,
    titleText = "App Name",
    titleCentered = false
)

And here is how to display a centered logo:

OctopusHomeScreen(
    navController = navController,
    titleCentered = true,
    logo = { painterResource(R.drawable.your_logo) }
)
info

For more advanced customization of the TopAppBar (colors, navigation icons, text styles), you can provide your own OctopusTopAppBar configuration at the theme level. See the Advanced Screen-Based Theming section below.

Advanced Screen-Based Theming (Android only)​

For more complex theming scenarios, you can customize any aspect of the Octopus theme (colors, typography, images, TopAppBar) based on the current screen:

octopusComposables(
    navController = navController
) { backStackEntry, content ->
    OctopusTheme(
        colorScheme = when {
            // Post Details with branded theme
            backStackEntry.destination.hasRoute<OctopusDestination.PostDetails>() -> {
                octopusColorScheme().copy(
                    background = if (isSystemInDarkTheme()) Color.Black else Color.White
                )
            }
            else -> octopusColorScheme()
        },
        topAppBar = when {
            // Home screen with custom TopAppBar theme
            backStackEntry.destination.hasRoute<OctopusDestination.Home>() -> {
                OctopusTopAppBarDefaults.topAppBar(
                    title = { text ->
                        OctopusTopAppBarTitle(text = "My Community")
                    }
                )
            }
            else -> OctopusTopAppBarDefaults.topAppBar()
        }
    ) {
        content()
    }
}

Push Notifications ≥ 1.4.0​

To increase user engagement, you can provide information to the Octopus SDK so your users can receive push notifications when other users interact with them inside the community.

note

Octopus SDK is not asking for push notification permissions, we let you handle that part where it makes more sense in your app.

If your app does not support Push Notifications yet, you can follow the official Firebase documentation.

Our servers need your service account's private key file to be authorized to send notifications to your app on your behalf.

If you don't have this JSON file yet, follow this tutorial
  • In the Firebase console, open Settings > Service Accounts
  • Click Generate New Private Key, then confirm by clicking Generate Key.
  • Securely store the JSON file containing the key.

More information can be found in the official Firebase documentation

Please send the json file using the online form sent by the Octopus team.

warning

This JSON file is different from the one you are using to configure Firebase in your app (google-services.json)

Once your project is correctly set up for push notifications, you should forward the Firebase Cloud Messaging Token (FCM Token) to the Octopus SDK:

class MessagingService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        super.onNewToken(token)

        // Register the new token with Octopus
        OctopusSDK.registerNotificationsToken(token)
    }
}
note
You are in charge of requesting the Notification permission and referencing your messaging service:
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
if (checkSelfPermission(POST_NOTIFICATIONS) != PackageManager.PERMISSION_GRANTED) {
    // Request launcher for notification permission
    registerForActivityResult(
        contract = ActivityResultContracts.RequestPermission(),
        callback = {
            FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
                if (task.isSuccessful) {
                    OctopusSDK.registerNotificationsToken(task.result)
                }
            }
        }
    ).launch(POST_NOTIFICATIONS)
}
<service
    android:name=".notifications.MessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

When you receive a notification message, first check if it is an Octopus notification by calling:

override fun onMessageReceived(remoteMessage: RemoteMessage) {
    super.onMessageReceived(remoteMessage)

    val isOctopusNotification = remoteMessage.data.isOctopusNotification
    if (isOctopusNotification) {
        // ... Handle the Octopus notification here (see below)
    }
}

If it's the case, display the Octopus notification using the Notification Manager:

val octopusNotification = OctopusSDK.getOctopusNotification(data = remoteMessage.data)
if (octopusNotification != null) {
    notificationManager.notify(
        octopusNotification.id,
        Notification.Builder(this, CHANNEL_ID)
            .setSmallIcon(R.drawable.ic_stat_notification)
            .setColor(getColor(R.color.accent))
            .setAutoCancel(true)
            // Extension function to extract the title, text and deep link from the OctopusNotification
            .setOctopusContent(
                context = this,
                activityClass = MainActivity::class,
                octopusNotification = octopusNotification
            ).build()
    )
}

Then you can display the notification's targeted Octopus UI from the octopusNotification.deepLink:

intent.data?.let { uri -> navController.navigate(deepLink = uri)}
note
  • The activityClass must be the one containing the compose content with the octopusNavigation() subgraph.
  • The setOctopusContent function is based on a deep link mechanism that will automatically launch the activity and navigate to the corresponding screen within the Octopus navigation graph.
  • You can also handle the content manually by using the OctopusNotification's title, body, and linkPath fields and configuring your own PendingIntent.

Not seen notifications ≥ 1.3.0​

To increase user engagement, let your users know that they have new notifications from the Octopus notification center. Displaying a badge with the number of new notifications in your app can be a great way to suggest your users to look at what's new in the community again.

To do that, the Octopus SDK exposes a val notSeenNotificationsCount: Flow<Int> that you can collect:

OctopusSDK.notSeenNotificationsCount.collect {}

If you want to update this value with the latest count, simply call:

OctopusSDK.updateNotSeenNotificationsCount()

To see a full example of how you can achieve that, you can follow how it is done in the Samples, in the Octopus Sample app.

Analytics​

Octopus Community provides analytics to help you better understand your users' behavior within the community. To improve the quality of these analytics, we offer features that allow you to provide additional information about your users.

Custom events ≥ 1.4.0​

You can tell the SDK to register a custom event. This event can be merged into the reports we provide.

Privacy notice

You're responsible for what you send through this API.

Don't transmit:

  • Sensitive data — health, religion, political opinions, sexual orientation, biometric or genetic data, criminal records
  • Payment details, government IDs, or login credentials
  • The content of private messages

Where privacy laws apply to your End Users (GDPR in the EEA/UK, CCPA in California, LGPD in Brazil, etc.), make sure you've obtained the necessary consent for analytics.

OctopusSDK.track(
    event = TrackerEvent.Custom(
        name = "Purchase",
        properties = mapOf(
            "price" to TrackerEvent.Custom.Property(
                value = String.format(Locale.US, "%.2f", 1.99)
            ),
            "currency" to TrackerEvent.Custom.Property(value = "EUR"),
            "product_id" to TrackerEvent.Custom.Property(value = "product1")
        )
    )
)

Community Visibility ≥ 1.3.0​

If you enable access to the community for only a subset of your users and want the analytics we provide to take this into account, you can inform the SDK accordingly.

This information is reset at each SDK launch so be sure to call the function everytime and as soon as possible after SDK init.

warning

This section is only useful when the host app (i.e. your app) manages its own A/B testing logic. Call this if your app is running its own A/B test and you want Octopus to log whether a given user is in the "community-enabled" or "control" group. This is useful for reporting and engagement analytics, but does not change the SDK’s runtime behavior.

≥ 1.6.0
OctopusSDK.trackAccessToCommunity(hasAccess = canAccessCommunity)
Deprecated < 1.6.0
OctopusSDK.setHasAccessToCommunity(canAccessCommunity)

Octopus Events ≥ 1.9.0​

As what the user does inside the Octopus UI is pretty opaque for you, we provide a way to register to be informed about events done by the user occuring inside Octopus.

If you have your own tracking service, you can use this publisher to listen to events that occured inside the Octopus UI part and feed your tracking service with them.

Privacy notice

Octopus emits these events locally inside your app — we don't send them anywhere.

If you forward them to your own analytics tools (Google Analytics, Firebase, Mixpanel, Amplitude, Contentsquare, etc.), you're responsible for that forwarding.

Where privacy laws apply to your End Users (GDPR in the EEA/UK, CCPA in California, LGPD in Brazil, etc.), make sure you've obtained the necessary consent for analytics.

Here is the list of all events and their params that are emitted from the Octopus SDK

Content

postCreated​

Sent when a post has been created by the current user.

Params:

  • postId: String — The id of the post.
  • content: PostContent — Content of the post. PostContent is a set of text, image and poll indicating the content of the post.
  • groupId: String ≥ 1.11.0 — The id of the group to which the post has been linked. (Was topicId before 1.11.0)
  • textLength: Int — The length of the text of this post.

commentCreated​

Sent when a comment has been created by the current user.

Params:

  • commentId: String — The id of the comment.
  • postId: String — The id of the post in which the comment has been posted.
  • textLength: Int — The length of the text of this comment.

replyCreated​

Sent when a reply has been created by the current user.

Params:

  • replyId: String — The id of the reply.
  • commentId: String — The id of the comment in which this reply has been posted.
  • textLength: Int — The length of the text of this reply.

contentDeleted​

Sent when a post, a comment or a reply has been deleted by the current user.

Params:

  • contentId: String — The id of the content that has been deleted.
  • kind: ContentKind — The kind of content. Can be post, comment or reply.

reactionModified​

Sent when a reaction is modified (added, deleted or changed) on a content by the current user.

Params:

  • previousReaction: ReactionKind? — The previous reaction. Can be null.
  • newReaction: ReactionKind? — The new reaction. If null, it means that the reaction has been deleted. ReactionKind is either heart, joy, mouthOpen, clap, cry or rage.
  • contentId: String — The id of the content.
  • contentKind: ContentKind — The kind of content. Can be post, comment or reply.

pollVoted​

Sent when the current user votes for a poll.

Params:

  • contentId: String — The id of the content (i.e. the post).
  • optionId: String — The id of the option voted by the user.

contentReported​

Sent when a content has been reported by the current user.

Params:

  • contentId: String — The id of the content.
  • reasons: [ReportReason] — The reasons of reporting this content.

Gamification

gamificationPointsGained​

Sent when gamification points are gained. Please note that only the points triggered by an in-app action are reported live.

Params:

  • pointsGained: Int — The points that have been added.
  • action: GamificationPointsGainedAction — The action that led to gaining points.

gamificationPointsRemoved​

Sent when gamification points are removed. Please note that only the points triggered by an in-app action are reported live. For example, if a post of this user gets moderated, you won't receive the information about points removed.

Params:

  • pointsRemoved: Int — The points that have been removed.
  • action: GamificationPointsRemovedAction — The action that led to losing points.

Navigation & UI

screenDisplayed​

Sent when the user navigates to a given screen.

Params:

  • screen: Screen — The screen that has been displayed.

    Screen can be:

    • mainFeed ≥ 1.10.0 — The main feed (i.e. list of posts selected for the user)

      Params:

      • feedId: String — The id of the feed that is displayed.

    • groups ≥ 1.10.0 — The groups list screen.

    • groupDetail ≥ 1.10.0 — The group detail screen with the posts of the group

      Params:

      • groupId: String — The id of the group that is displayed.
      • source ≥ 1.11.0 — The source from which this screen was opened. Can be bridge (opened from the client app via bridge mode) or community (opened from within the SDK community).

    • postDetail — The post detail screen with the list of comments

      Params:

      • postId: String — The id of the post that is displayed.

    • commentDetail — The comment detail screen with the list of replies

      Params:

      • commentId: String — The id of the comment that is displayed.

    • createPost — The create post screen

    • profile — The user profile screen

    • otherUserProfile — The profile screen of another Octopus user

      Params:

      • profileId: String — The id of the profile that is displayed.

    • editProfile — The edit profile screen

    • reportContent — The report content screen

    • reportProfile — The report profile screen

    • validateNickname — The validate nickname screen (displayed after a user with a non-modified nickname has created a post)

    • settingsList — The settings screen

    • settingsAccount — The account settings screen. Only visible if the SDK is configured in Octopus authentication (not SSO)

    • settingsAbout — The about settings screen

    • reportExplanation — The report explanation screen

    • deleteAccount — The delete account screen. Only visible if the SDK is configured in Octopus authentication (not SSO)

    • postsFeed — The posts feed (i.e. list of posts) ⚠️ Deprecated since 1.10.0 — split into mainFeed and groupDetail.

      Params:

      • feedId: String — The id of the feed that is displayed.
      • relatedTopicId: String? — The id of the group related to this feed. Null if the feed is not representing a group or is multi-group (for example, the feed "For You").

notificationClicked​

Sent when the user clicks on an internal notification (from the Octopus Notification Center).

Params:

  • notificationId: String — The id of the notification.
  • contentId: String? — The target content id. Can be null if the notification does not target a content.

postClicked​

Sent when the user clicks on a post.

Params:

  • postId: String — The id of the post.
  • source: PostClickedSource — The source of the click. Can be feed (if the post was displayed in the posts feed) or profile (if the post was displayed in a user profile posts list).

translationButtonClicked​

Sent when the user clicks on a translation button.

Params:

  • contentId: String — The id of the content.
  • viewTranslated: Bool — Whether the user wants to display the translated or the original content.
  • contentKind: ContentKind — The kind of content. Can be post, comment or reply.

commentButtonClicked​

Sent when the user clicks the comment button of a post.

Params:

  • postId: String — The id of the post.

replyButtonClicked​

Sent when the user clicks the reply button of a comment.

Params:

  • commentId: String — The id of the comment.

seeRepliesButtonClicked​

Sent when the user clicks on the replies button of a comment.

Params:

  • commentId: String — The id of the comment.

Profile

profileModified​

Sent when the profile is modified by the user.

Params:

  • nickname: ProfileFieldUpdate<NicknameUpdateContext> — The nickname update information. Either unchanged or changed.

  • bio: ProfileFieldUpdate<BioUpdateContext> — The bio update information. Either unchanged or changed.

    BioUpdateContext params:

    • bioLength: Int — The length of the bio.

  • picture: ProfileFieldUpdate<PictureUpdateContext> — The picture update information. Either unchanged or changed.

    PictureUpdateContext params:

    • hasPicture: Int — Whether the user has added a picture or deleted the existing one.

Session

sessionStarted​

Sent when an Octopus UI session is started.

Params:

  • sessionId: String — The id of the session.

sessionStopped​

Sent when an Octopus UI session is stopped (call either when the Octopus UI is closed or when the app is put in background).

Params:

  • sessionId: String — The id of the session.

Types

ContentKind​

Can be post, comment or reply.

ReactionKind​

Can be heart, joy, mouthOpen, clap, cry or rage.

PostContent​

A set of text, image and poll indicating the content of the post.

Here is how to listen to these events:

// Listen to Octopus Events and convert into events for your analytics tool,
// for example here with Firebase Analytics
OctopusSDK.events.collect { event ->
    when(event) {
        is PostCreated -> {
            FirebaseAnalytics.getInstance().logEvent(
                name = "post_created",
                params = Bundle().apply {
                    putString("group", event.groupId) // event.topicId before 1.11.0
                    putInt("text_length", event.textLength)
                    putBoolean("has_poll", event.content.contains(POLL)
                    putBoolean("has_image", event.content.contains(IMAGE)
                }
            )
        }
        else -> { //... }
    }
}

Groups​

Groups are content categories users follow. The SDK exposes the list of groups available in the community, each group's follow state for the current user, and a programmatic API to set that follow state from the client.

List available groups and read their state​

The SDK publishes the list of groups as observable state and exposes a method to force a refresh from the server. Each group carries its identifier, display name, and the connected user's current follow state — including whether the user is allowed to change that state.

// Get cached groups
OctopusSDK.groups.collect { groups ->
    // groups: List<OctopusGroup>
    // each has: id, name, isFollowed, canChangeFollowStatus
}

// Fetch the latest groups from the server
OctopusSDK.fetchGroups()
Deprecated < 1.11.0
OctopusSDK.topics.collect { topics ->
    // List of available topics
}

OctopusSDK.fetchTopics()

Sync follow state in batch ≥ 1.11.0​

Client apps can push a batch of follow/unfollow actions for the current user, with a per-action timestamp. The backend reconciles each action against the user's manual actions: if the user has manually acted on a group more recently than the client's actionDate, the client action is silently skipped. Essential (i.e. force-followed) groups always stay followed — client attempts to unfollow them are rejected.

Parameters for each action:

  • groupId: String — the id of the group to follow or unfollow.
  • followed: Bool — true to follow, false to unfollow.
  • actionDate: Date — the date at which the client observed the action. The backend compares this to the last recorded action for the (user, group) pair.
val actions = listOf(
    SyncFollowGroupAction(groupId = "g1", followed = true,  actionDate = Date()),
    SyncFollowGroupAction(groupId = "g2", followed = false, actionDate = Date()),
)

when (val result = OctopusSDK.syncFollowGroups(actions = actions)) {
    is OctopusResult.Success -> {
        for (r in result.data) {
            // r.groupId — the group this result refers to
            when (r.status) {
                is SyncFollowGroupStatus.Applied            -> {} // action was applied
                is SyncFollowGroupStatus.Skipped            -> {} // user acted more recently — client action ignored
                is SyncFollowGroupStatus.AlreadyFollowed    -> {} // user already follows — no change
                is SyncFollowGroupStatus.AlreadyUnfollowed  -> {} // user already does not follow — no change
                is SyncFollowGroupStatus.GroupNotFound      -> {} // no group with that id
                is SyncFollowGroupStatus.NotFollowable      -> {} // group is admin-restricted
                is SyncFollowGroupStatus.NotUnfollowable    -> {} // essential (i.e. force-followed) group
                is SyncFollowGroupStatus.UnknownError       -> {} // unclassified server error for this action
            }
        }
    }
    is OctopusResult.Failure -> {
        // Handle the transport-level failure (NoNetwork, UserNotAuthenticated, StatusError, …)
    }
}
tip

Typical triggers for this API are lifecycle events in your app: app launch, onboarding completion, a premium unlock, or a preference change that should pre-shape the user's community experience.

Bridges ≥ 1.5.0​

Octopus provides a way of linking a specific object in your app (e.g. a page, a product, any kind of content) to a dynamic post in the community, created automatically. We call this a bridge. To create a bridge, your content (an article, a product, etc.) must have a unique identifier. This ID will be used to link your content to the post. It will also allow users in the Octopus Community to directly view your content.

The bridge process involves four main steps:

Step 1: Prepare the post data Use the SDK to get (or create) the ID of the post related to your content. First get from the SDK the id of the post to display. The SDK will create the post if it is not already created. To do that, call the dedicated API and pass the required data:

  • Content id (called clientObjectId) that the post will be about
  • Text of the post. It must be between 10 and 5000 (3000 before the 1.8.0) characters.
  • Catchphrase (optional). It will be displayed below the title, in bold. You can use something like "What do you think about this?". It must be less than 84 characters and we recommend between 6 and 38 characters.
  • Image for the post (optional). You can either pass a remote image using an URL or a local image. The image must respect these requirements:
    • File size must be less than 50Mb
    • File format must be jpg or png
    • Image sides must be between 50px and 4000px, with a max ratio of 32:9 (bigger side / smaller side)
    • If you pass a remote image, the resource should be public
  • Text of the button that will invite your users to display your content (optional). You can use something like "Buy it" if your content is a purchasable product, or "Read the article" if it is a press article. When the button containing this text will be tapped, the SDK will ask you to display your content. If no text is provided, the button won't be displayed. It must be less than 28 characters, we recommend between 4 and 28 characters.
  • Group id (optional) ≥ 1.11.0 (was "Topic id"). This is the id of the group that you want the post to be labelled with. If not provided, the group will be automatically set according to your community settings. See the Groups section to retrieve the list of available groups.
  • Signature (Deprecated < 1.10.0): replaced by enhanced security in the fetchOrCreateClientObjectRelatedPost function using a callback and a unique token per post.
val clientPost = ClientPost(
    objectId = "recipe-129302938", // A unique identifier for your content
    text = "The perfect Canelés", // Between 10 and 5000 chars
    attachment = Image.Remote(url = imageUrl), // You can also pass Image.Local(uri)
    groupId = foodRecipeGroupId, // The id of the Octopus group. Null if default.
    catchPhrase = "Tried the canelés? Tell us how good they were!", // Less than 84 characters
    viewObjectButtonText = "Read the recipe" // Less than 28 characters
)
Deprecated < 1.11.0
val clientPost = ClientPost(
    objectId = "recipe-129302938",
    text = "The perfect Canelés",
    attachment = Image.Remote(url = imageUrl),
    topicId = foodRecipeId, // renamed to `groupId` in 1.11.0
    catchPhrase = "Tried the canelés? Tell us how good they were!",
    viewObjectButtonText = "Read the recipe"
)

Step 2: Get the post ID

Calling the API with the previously created post data will return a post ID. With this ID, you can display the post using the Octopus UI. If the post is not created, this API will create it, otherwise it won't change its content.

To ensure security, you must provide a callback called tokenProvider. The SDK calls this callback only when a new post needs to be created, to get the post signature from you. For maximum security (recommended), you should compute the bridge fingerprint yourself on the backend. You can find how to do it in the Generate fingerprint for bridge documentation. Alternatively, with reduced security, you can use the bridge fingerprint provided by the callback. In both cases, with the fingerprint, you should ask your server to sign it (see Generate token for bridge documentation for details on how to do this).

val result = OctopusSDK.fetchOrCreateClientObjectRelatedPost(
    clientPost = clientPost,
    tokenProvider = { bridgeFingerprint ->
        // For more security, ignore the bridgeFingerprint and get the jwt directly from a fingerprint
        // computed on your backend.
        // Otherwise, call your backend /generateBridgeSignature route with the bridgeFingerprint.
        // `server` represents your own backend client — replace with your actual implementation.
        // Return null if your community does not require a signature.
        server.getBridgeSignature(bridgeFingerprint)
    }
)
when (result) {
    is OctopusResult.Success -> {
        val post = result.data
        val postId = post.id
        // Navigate to the post or handle success
    }
    is OctopusResult.Error -> {
        // Handle error
    }
}
Deprecated < 1.10.0
// fetchOrCreateClientObjectRelatedPost without tokenProvider
val result = OctopusSDK.fetchOrCreateClientObjectRelatedPost(clientPost)

Step 3: Handle user interaction

Optionally, you can register a callback to be notified when a user wants to view your content from a bridge post. The SDK will provide the clientObjectId so you can open the appropriate content.

// In your NavHost setup
octopusComposables(
    // ...
    onNavigateToClientObject = { objectId ->
        // Display the content that has the given objectId
    }
)
info

Note that if you don't set onNavigateToClientObject, the button containing the viewObjectButtonText you passed in the ClientPost won't be displayed.

Step 4: Display the post

Using the post id, you can display it directly after the user taps a button on your object page. See Open a specific screen for the per-platform integration details.

OctopusPostDetailsContent(
    modifier = Modifier.fillMaxSize(),
    postId = postId,
    // ...
)

Optional: accessing live data about the post > 1.7.0

Additionaly to the post id, we also provide more information about the post. You can access and display the reaction count that all Octopus users did on the post, the number of comments and the number of views.

You can retrieve an object that references the post and that will be updated with the current value and as soon as you call the fetchOrCreateClientObjectRelatedPost function.

OctopusSDK.getClientObjectRelatedPostFlow(clientObjectId = "recipe-129302938")
    .filterNotNull()
    .collect { post ->
        val reactions = post.reactions // Reactions is List<OctopusReactionCount> and OctopusReactionCount is a data class with a reaction and a count
        val commentCount = post.commentCount
        val viewCount = post.viewCount
    }

Optional: reading the current user's reaction ≥ 1.9.1

You can read the current user's reaction on a bridge post from the post object. This is useful if you want to display the user's reaction in your own UI outside of Octopus.

OctopusSDK.getClientObjectRelatedPostFlow(clientObjectId = "recipe-129302938")
    .filterNotNull()
    .collect { post ->
        val userReaction = post.userReactionKind // OctopusReactionKind? — null if the user has not reacted
    }

Optional: setting a reaction on a bridge post ≥ 1.9.1

If you display bridge post data in your own UI, you can let users react to the post without entering the Octopus Community screen. Pass a reaction kind to set a reaction, or pass null/nil to remove it.

Available reaction kinds: heart ❤️, joy 😂, mouthOpen 😮, clap 👏, cry 😢, rage 😡.

// Set a reaction
OctopusSDK.setReaction(
    reaction = OctopusReactionKind.Heart,
    clientObjectRelatedPostId = "recipe-129302938"
)

// Remove the reaction
OctopusSDK.setReaction(reaction = null, clientObjectRelatedPostId = "recipe-129302938")

To see a full example of how you can achieve that, you can follow how it is done in the Samples:

in the Octopus Sample app. The MainViewModel is in charge of preparing the client post and getting the post.

Octopus A/B Testing ≥ 1.6.0​

The A/B test feature lets you measure the impact of the community on your app usage by splitting your audience into two cohorts:

  • Test group: a portion of users (e.g., 30%) with full access to the community.
  • Control group: the remaining users (e.g., 70%) without access. For them, when they tap the community button, Octopus displays a screen: “The community is not available yet for you, please come back later.” In Octopus Analytics, you’ll then see clear comparisons between these two cohorts in terms of app session volume and retention.

Even if this A/B Test is totally internal, we let you know whether the user can access the community or not (i.e., in which group the user is).

We also let you override the group assigned to the connected user. This can be useful during your tests to check what will see the users of each group or even to provide or disable access to some given users.

Use this method when you need to guarantee that the user’s community access is enforced by Octopus, regardless of internal A/B testing rules.

Here is how to override the user community access:

OctopusSDK.overrideCommunityAccess(hasAccess = canAccessCommunity)

Here is how to know whether the current user has access to the community. It is a published value that is updated as soon as the user group changes. ≥ 1.6.1

OctopusSDK.hasAccessToCommunity.collect { hasAccessToCommunity ->
    // Use the hasAccessToCommunity new value
}

To see a full example of how you can achieve that, you can follow how it is done in the Samples, in the Octopus Sample app.

Intercept URL openings ≥ 1.9.0​

Users can open links from the SDK. These URLs can either be opened from a link tapped on a post/comment/reply content, or from a Post with CTA button tap. These links will be opened by default in the web browser. Octopus SDK lets you the ability to catch these URL opening and decide what to do with the URL. Either using it yourself to do whatever you want or let Octopus handle them. You could, for example, catch any URL opening your website and instead opening the correct page in your own app.

// Set the callback that will be called when a user tries to open a link inside the community.
// This link can come from a Post/Comment/Reply or when tapping on a Post with CTA button.
octopusComposables(
    // ...
    onNavigateToUrl = { url ->
        val uri = url.toUri()
        if(uri.host == "www.yourdomain.com" && uri.path == "/contact") {
            // Open the contact page inside the app
            ...

            // Link has been handled by app, let the Octopus SDK know that it should do nothing more
            return HandledByApp
        }

        // Let the SDK handle the other links by returning `HandledByOctopus`
        return HandledByOctopus
    }
)

To see a full example of how you can achieve that, you can follow how it is done in the Samples, in the UrlHandler.

Override the language ≥ 1.9.0​

On both iOS and Android, the system lets the user choose a language for their device and also lets them customize this language per app. Some apps do not use this standard way of handling the language. If you have a custom setting inside your app that does not set the system app language, you can call a function of Octopus in order to customize the language used (so Octopus does not use the system language but yours instead).

That being said, we recommend using the default system way of handling the locale, so system alerts and system screens (like the picture selection screen) are displayed in the desired language.

OctopusSDK supports these languages: English, French, German, Italian, Polish, Portuguese, Spanish, Swedish, Turkish. Passing another locale will fallback to the default language (english).

warning

No check can be done on the Locale you pass, so ensure it is a valid Locale. If the locale is not valid, it will fallback on the default language (english).

// Override the default (i.e. system or app based) locale.
// You can pass a Locale for a language only, or build one with a region.
// The language must be a two-letter ISO 639-1 code; the region (optional) a two-letter ISO 3166-1 code.

// only a language
OctopusSDK.overrideDefaultLocale(Locale.FRENCH)

// a language and a region (will use Portuguese inside Octopus because Brazilian Portuguese is not supported)
OctopusSDK.overrideDefaultLocale(Locale("pt", "BR"))

Follow the Samples​

Want to see code examples on how to use the SDK, no worries, we have that for you!

  1. First, clone the OctopusSDK project

    Android SDK

  2. Add those lines to the root project local.properties file:

    OCTOPUS_API_KEY=YOUR_API_KEY
    OCTOPUS_SSO_CLIENT_USER_TOKEN_SECRET=YOUR_USER_TOKEN_SECRET

    Replace YOUR_API_KEY with your own API key and YOUR_USER_TOKEN_SECRET with your own token secret.

  3. According to your desired UI integration mode choose the corresponding sample: