Skip to main content

Configuration and lifecycle

Point the SDK at a custom server, open Octopus screens from your deep links, switch communities at runtime, and control the SDK lifecycle.

Before you begin​

How it works​

The SDK holds one community at a time, identified by the API key you pass at initialization. Four lifecycle operations change that state:

OperationUser sessionLocal SDK dataSDK stays initializedCommunity
InitializeStarts emptyKeptYesThe one from the API key
Switch communityEndedClearedYesThe new one
ResetEndedCleared, on Android onlyYesUnchanged
StopNot endedKeptNoNone until you initialize again

After a switch or a reset, reconnect your user and rebuild any community screen on display. After a stop, initialize the SDK again before you call anything else.


Point the SDK at a custom server​

Android ≥ 1.12.0iOS ≥ 1.12.0Flutter ≥ 1.12.0React Native ≥ 1.13.0Unity ≥ 1.12.2

By default, the SDK talks to the Octopus production endpoint. Pass a server only when Octopus gives you a dedicated host. Traffic always uses TLS.

The host is a DNS name, an IPv4 address or an IPv6 address. It carries no scheme, port, path or whitespace: api.example.com is valid, https://api.example.com is not. The port defaults to 443.

Parameters of ApiServer:

  • host (String): required.
  • port (Int): optional, default 443.
import com.octopuscommunity.sdk.ApiServer
import com.octopuscommunity.sdk.OctopusSDK
import com.octopuscommunity.sdk.domain.model.ConnectionMode

OctopusSDK.initialize(
context = applicationContext,
apiKey = "YOUR_API_KEY",
connectionMode = ConnectionMode.SSO(),
apiServer = ApiServer(host = "api.example.com"),
)
warning

ApiServer throws ApiServer.ValidationError, an IllegalArgumentException, when the host is empty, contains a scheme, a port, a path or whitespace, or has invalid IPv6 brackets.


Android availableiOS not availableFlutter not availableReact Native not availableUnity not available

The SDK can register its screens under your own deep link base paths. A link such as https://www.example.com/community/post/create then opens the post creation screen inside your navigation graph.

The SDK appends a / to each base path when it is missing, then adds the sub-path of the screen:

Sub-pathScreen
(empty) or homeCommunity home
post/createPost creation
post/{postId}/comment/{commentId}A comment in its post
comment/{commentId}/reply/{replyId}A reply in its comment thread
current-profileThe user's own profile
current-profile/editThe user's profile editor

Since 1.15.0, account management belongs to your app: the settings, settings/profile, settings/delete-account, magic-link/email and magic-link/confirm sub-paths no longer exist. The validate-nickname link closes immediately when no contribution is waiting.

Pass deepLinksBasePaths to initialize, or to switchCommunity. The deep links are attached to the destinations that octopusComposables registers.

OctopusSDK.initialize(
context = applicationContext,
apiKey = "YOUR_API_KEY",
connectionMode = ConnectionMode.SSO(),
deepLinksBasePaths = listOf("https://www.example.com/community"),
)

Then declare an intent filter for the same base path on the activity that hosts your NavHost:

<activity android:name=".MainActivity" android:exported="true">
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data
android:scheme="https"
android:host="www.example.com"
android:pathPrefix="/community" />
</intent-filter>
</activity>
note

The SDK does not declare any intent filter. Without yours, Android never routes the link to your app.


Switch community​

Use switchCommunity when your app serves several communities with different API keys. It flushes pending analytics events, signs out the current user, clears cached user data and files, then initializes the SDK on the new API key.

switchCommunity also works when the SDK is not initialized: it initializes it on the new community.

warning
  • Do not call any other Octopus function until switchCommunity completes.
  • When it completes, reconnect your signed-in user with connectUser.
  • Rebuild any community screen on display, so it binds to the new community.

The OctopusSDK object stays the same after the switch; only its internal state changes.

Parameters:

  • context (Context): required. The application context.
  • apiKey (String): required. The API key of the new community.
  • connectionMode (ConnectionMode): required, with no default ≥ 1.15.0. Pass ConnectionMode.SSO(…), with the same configuration as at initialization.
  • deepLinksBasePaths (List<String>): optional, default empty. See deep links.
  • apiServer (ApiServer?): optional, default null. See custom server.

switchCommunity and connectUser are suspend functions: call them from a coroutine.

import com.octopuscommunity.sdk.OctopusSDK
import com.octopuscommunity.sdk.domain.model.ClientUser
import com.octopuscommunity.sdk.domain.model.ConnectionMode
import com.octopuscommunity.sdk.domain.model.ProfileField
import com.octopuscommunity.sdk.domain.model.Resource
import com.octopuscommunity.sdk.domain.network.OctopusResult

lifecycleScope.launch {
OctopusSDK.switchCommunity(
context = applicationContext,
apiKey = "NEW_COMMUNITY_API_KEY",
connectionMode = ConnectionMode.SSO(
appManagedFields = setOf(ProfileField.NICKNAME, ProfileField.PICTURE)
),
)

// Reconnect the signed-in user to the new community
val result = OctopusSDK.connectUser(
ClientUser(
userId = yourUser.id,
profile = ClientUser.Profile(
nickname = yourUser.name,
bio = yourUser.bio,
picture = yourUser.avatarUrl?.let { Resource.Remote(it) },
),
)
) {
// Fetch the user token from your backend
fetchOctopusToken()
}
when (result) {
is OctopusResult.Success -> { /* The user is connected */ }
is OctopusResult.Failure -> { /* Show an error or retry */ }
}
}

After the switch, rebuild the navigation entries that host SDK screens: their ViewModels belong to the previous SDK container. Then reconnect your signed-in user with connectUser.


Reset and stop the SDK​

Android availableiOS not availableFlutter ≥ 1.12.0React Native ≥ 1.13.0Unity ≥ 1.13.0

  • Reset signs out the user and clears the local SDK data. The SDK stays initialized on the same community. Use it for a full sign-out of your app.
  • Stop releases the SDK. Initialize it again, or switch community, before any other call.

reset() is a suspend function. It ends the session and removes the SDK data stored on the device: user data, content and cached images. stop() cancels ongoing operations and keeps the data. Both do nothing when the SDK is not initialized.

lifecycleScope.launch {
// Sign out and clear the local data; the SDK stays initialized
OctopusSDK.reset()
}

// Release the SDK; call initialize() or switchCommunity() before reusing it
OctopusSDK.stop()
note

Flows you collect from the SDK do not complete on stop(). They emit again once you initialize the SDK. After stop() or switchCommunity(), rebuild navigation entries that host SDK screens before opening them again.


Check whether the SDK is initialized​

Android availableiOS not availableFlutter ≥ 1.12.0React Native ≥ 1.13.0Unity not available

Read the initialization state to gate a splash screen, or observe it to update your UI when the SDK starts or stops. It becomes true after initialize or switch community, and false after stop. Reset does not change it.

import com.octopuscommunity.sdk.OctopusSDK
import com.octopuscommunity.sdk.domain.model.ConnectionMode

if (!OctopusSDK.isInitialised) {
OctopusSDK.initialize(
context = applicationContext,
apiKey = "YOUR_API_KEY",
connectionMode = ConnectionMode.SSO(),
)
}

// Observe the state
lifecycleScope.launch {
OctopusSDK.isInitialisedFlow.collect { ready -> showCommunityEntry(ready) }
}

App-managed audio session​

Android not availableiOS availableFlutter not availableReact Native ≥ 1.15.0Unity ≥ 1.15.0

Let your app configure and activate the audio session during community video playback. The default keeps audio-session management in the SDK.

App-managed audio session configuration is not available on Android.


Behavior and limits​

  • What each lifecycle operation keeps or clears is summarized in How it works, and the versions per platform are in Platform support.
  • A failed switch does not restore the previous community. Initialize again or retry the switch.
  • A custom server is not remembered across a switch. Pass it again on every call that must stay on it.

Next steps​