Getting Started

Welcome! This guide walks you through the minimum 3 steps to get Octopus SDK running in your app.

Step 1: Request your API key
Step 2: Install the SDK
Step 3: Display the UI

1) Get an API Key

Fill out the form to request your API key. Required fields: Email, First Name, Last Name. Company is optional.

2) Install the SDK

Choose your platform and install the SDK:

Android
iOS
Flutter
React Native
Unity

Add Maven Central and the dependencies in your Gradle files:

// build.gradle (project)
allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

// build.gradle (module)
dependencies {
    // Core SDK functionalities
    implementation("com.octopuscommunity:octopus-sdk:<latest>")
    // Compose UI components — required for step 3
    implementation("com.octopuscommunity:octopus-sdk-ui:<latest>")

    // Compose and Navigation, used directly by the step 3 snippet.
    // The SDK uses them internally but does not expose them to your
    // compile classpath, so declare them yourself.
    implementation("androidx.activity:activity-compose:<latest>")
    implementation("androidx.navigation:navigation-compose:<latest>")
}

Initialize the SDK early in your app (e.g., Application):

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

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        OctopusSDK.initialize(
            context = this,
            apiKey = BuildConfig.OCTOPUS_API_KEY, // store securely
            connectionMode = ConnectionMode.OctopusAuth
        )
    }
}

Why connectionMode is explicit here

ConnectionMode.OctopusAuth lets Octopus handle sign-in, which is what makes the 3-step path work with no further wiring. The default is ConnectionMode.SSO() — your app owns the user — and in that mode the UI requires an onNavigateToLogin callback: without it the SDK throws as soon as a community screen renders. Pick SSO once you are ready to wire it, and follow the SDK Setup Guide rather than this page.

Install via Swift Package Manager, with the URL:

https://github.com/Octopus-Community/octopus-sdk-swift.git

Add both products to your target — Octopus and OctopusUI. The UI lives in OctopusUI, so a target that only gets Octopus cannot see the screens of step 3.

Create the SDK object once and keep it alive — the UI takes it as a parameter, so it must outlive the view:

import Octopus

final class OctopusProvider {
    static let shared = OctopusProvider()

    let octopus: OctopusSDK

    private init() {
        octopus = try! OctopusSDK(
            apiKey: Bundle.main.object(forInfoDictionaryKey: "OCTOPUS_API_KEY") as? String ?? ""
        )
    }
}

The initializer is throws, so it cannot be called at file scope — Swift does not allow a throwing call in a global initializer. Keep it inside a type, as above. try! traps on an invalid API key, which is what you want while integrating; switch to try and your own error path once the key comes from remote config.

The default connection mode is Octopus-managed sign-in, so nothing else is needed to get to step 3. For app-managed users, see the SDK Setup Guide.

The Flutter SDK is on pub.dev and has its own Android and iOS setup steps (Gradle minSdk, iOS deployment target, push credentials).

→ SDK Setup Guide — Flutter

Replace <latest> with the current version and inject your API key via secure config.

3) Display the UI

Once the SDK is installed and initialized, present the community UI:

Android
iOS
Flutter
React Native
Unity

Add the OctopusHomeScreen composable — a complete screen with its own Scaffold and top bar. It navigates to the Octopus sub-screens through a NavHostController you own, so register octopusComposables() on the same NavHost:

import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Modifier
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.compose.rememberNavController
import com.octopuscommunity.sdk.ui.home.OctopusHomeScreen
import com.octopuscommunity.sdk.ui.octopusComposables

// in your Activity's onCreate
setContent {
    val navController = rememberNavController()

    NavHost(navController = navController, startDestination = "Home") {
        composable("Home") {
            OctopusHomeScreen(
                navController = navController,
                modifier = Modifier.fillMaxSize()
            )
        }

        octopusComposables(navController = navController)
    }
}

Use OctopusHomeContent instead to embed the community inside your own layout (a tab, a bottom sheet, your own Scaffold). The sample app in the Android repository ships one build variant per integration mode, so you can run the one closest to your app (it needs your API key in local.properties).

From a SwiftUI view, pass the SDK object you created above. The screens live in the OctopusUI product, so import it — import Octopus alone does not expose them:

import OctopusUI

struct CommunityView: View {
    var body: some View {
        OctopusHomeScreen(octopus: OctopusProvider.shared.octopus)
    }
}

Pushed normally into your navigation, the default .automatic mode is the right choice. Presenting it inside a modal instead — a .sheet, a .fullScreenCover — opt into navigationMode: .navigationStack, otherwise the legacy navigation can silently drop in-app pushes (tapping a post no longer opens its detail):

.sheet(isPresented: $showCommunity) {
    OctopusHomeScreen(
        octopus: OctopusProvider.shared.octopus,
        navigationMode: .navigationStack
    )
}

On iOS 16 and later this uses NavigationStack; below 16 the SDK falls back to the legacy navigation API. See the SDK Setup Guide for the full set of presentation modes.

1) Get an API Key​

Request an API Key

2) Install the SDK​

3) Display the UI​

1) Get an API Key

2) Install the SDK

3) Display the UI