Quickstart

Add the Octopus SDK to your app, initialize it, open the community and connect your signed-in user. Pick your platform once: every tab below follows it.

Before you begin

• A sandbox API key. Octopus creates two communities for you, a sandbox and a production one, each with its own API key. Use the sandbox key while you integrate, so your test content never reaches your real users.
• A supported toolchain. Check the minimum OS and tool versions in Requirements.
• Optional: a token route on your backend. Connecting your own users needs a JWT signed by your backend. You can install the SDK and open the community first, then add the route with Generate a signed JWT.

---

1. Install the SDK

Android

The SDK is published on Maven Central. Add it to your app module, with Navigation Compose to host its screens:

// app/build.gradle.kts
dependencies {
    implementation("com.octopuscommunity:octopus-sdk:1.14.2")
    implementation("com.octopuscommunity:octopus-sdk-ui:1.14.2")
    implementation("androidx.activity:activity-compose:1.10.1")
    implementation("androidx.navigation:navigation-compose:2.9.5")
}

Your app needs mavenCentral() in its repositories, minSdk 21 or higher and Jetpack Compose with Material 3.

iOS

Add the package with Swift Package Manager. In Xcode, choose File > Add Package Dependencies, enter the URL below, then add the Octopus and OctopusUI products to your app target. In a Package.swift:

dependencies: [
    .package(url: "https://github.com/Octopus-Community/octopus-sdk-swift.git", from: "1.14.0")
],
targets: [
    .target(name: "YourApp", dependencies: [
        .product(name: "Octopus", package: "octopus-sdk-swift"),
        .product(name: "OctopusUI", package: "octopus-sdk-swift"),
    ])
]

CocoaPods also works: pod 'OctopusCommunity', '~> 1.14' and pod 'OctopusCommunityUI', '~> 1.14'.

Flutter

flutter pub add octopus_sdk_flutter

Two one-time native steps:

• Android: MainActivity must extend FlutterFragmentActivity, not FlutterActivity.
• iOS: set the deployment target to 14.0.

// android/app/src/main/kotlin/.../MainActivity.kt
import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity : FlutterFragmentActivity()

React Native

npm install @octopus-community/react-native

On iOS the native SDK must be linked statically. Enable it in your Podfile, then run pod install:

# ios/Podfile
use_frameworks! :linkage => :static

With Expo, set the same option through expo-build-properties:

["expo-build-properties", { "ios": { "useFrameworks": "static" } }]

Unity

Add the package and the External Dependency Manager to Packages/manifest.json:

{
  "dependencies": {
    "com.google.external-dependency-manager": "https://github.com/googlesamples/unity-jar-resolver.git?path=upm#v1.2.187",
    "com.octopuscommunity.octopus_sdk_for_unity": "https://github.com/Octopus-Community/octopus-sdk-unity.git?path=UnityPackage#v1.14.0"
  }
}

If your project does not use the Unity Package Manager, import the OctopusCommunitySDK.unitypackage of the release instead.

---

2. Initialize the SDK

Initialize the SDK once, when your app starts, with your API key. The examples below use the SSO connection mode with no app-managed fields: your app signs users in, and members edit their community profile inside the community. To let your app own the nickname, bio or picture, or to let Octopus run its own sign-in flow, see Connect your users.

Android

Call OctopusSDK.initialize from your Application:

import android.app.Application
import com.octopuscommunity.sdk.OctopusSDK
import com.octopuscommunity.sdk.domain.model.ConnectionMode

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

iOS

Create one OctopusSDK instance and keep it for the life of your app. The loginRequired block runs when a member who is not signed in tries an action that needs an account:

import Octopus

let octopus = try OctopusSDK(
    apiKey: "YOUR_API_KEY",
    connectionMode: .sso(.init(loginRequired: {
        // Start your app's sign-in flow
    }))
)

Flutter

import 'package:flutter/material.dart';
import 'package:octopus_sdk_flutter/octopus_sdk_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await OctopusSDK().initialize(apiKey: 'YOUR_API_KEY');
  runApp(const MyApp());
}

React Native

import { initialize } from '@octopus-community/react-native';

initialize({
  apiKey: 'YOUR_API_KEY',
  connectionMode: { type: 'sso', appManagedFields: [] },
}).catch(console.error);

Unity

void Start()
{
    OctopusSDK.Initialize("YOUR_API_KEY", ConnectionMode.SSO());
}

tip

In the Unity Editor, the SDK runs in Unity Editor Mock Mode, so you can build your UI before you test on a device.

---

3. Show the community

Open the community from one entry point in your app, such as a button or a tab. Display the community covers every other way to present it.

Android

Host OctopusHomeScreen in a NavHost, and register the SDK's other screens with octopusComposables. In SSO mode, onNavigateToLogin opens your sign-in screen:

import com.octopuscommunity.sdk.ui.home.OctopusHomeScreen
import com.octopuscommunity.sdk.ui.octopusComposables

setContent {
    val navController = rememberNavController()
    NavHost(navController = navController, startDestination = "community") {
        composable("community") {
            OctopusHomeScreen(
                navController = navController,
                onNavigateToLogin = { /* Open your sign-in screen */ },
            )
        }
        octopusComposables(
            navController = navController,
            onNavigateToLogin = { /* Open your sign-in screen */ },
        )
    }
}

iOS

Present OctopusHomeScreen. Keep navigationMode: .navigationStack when you present it modally:

import SwiftUI
import OctopusUI

struct ContentView: View {
    let octopus: OctopusSDK
    @State private var showCommunity = false

    var body: some View {
        Button("Open community") { showCommunity = true }
            .fullScreenCover(isPresented: $showCommunity) {
                OctopusHomeScreen(octopus: octopus, navigationMode: .navigationStack)
            }
    }
}

Flutter

OctopusHomeScreen is a widget. Push it like any other route:

Navigator.of(context).push(MaterialPageRoute(
  builder: (_) => OctopusHomeScreen(
    navBarTitle: 'Community',
    onNavigateToLogin: () {/* Open your sign-in screen */},
  ),
));

React Native

openUI() opens the community full screen. In SSO mode, listen for sign-in requests:

import { Button } from 'react-native';
import { addLoginRequiredListener, openUI } from '@octopus-community/react-native';

addLoginRequiredListener(() => {
  // Open your sign-in screen
});

export function CommunityButton() {
  return <Button title="Community" onPress={() => openUI()} />;
}

Unity

OctopusSDK.Open() opens the community full screen. In SSO mode, listen for sign-in requests:

void Awake()
{
    OctopusSDK.OnLoginRequired += () => { /* Open your sign-in flow */ };
}

public void OnCommunityButton() => OctopusSDK.Open();

---

4. Connect your user

When a user signs in to your app, pass their id to connectUser with a token provider. The SDK calls the token provider each time it needs a fresh JWT, which your backend signs (see Generate a signed JWT). Until then, members browse the community as guests. Call disconnectUser when they sign out. Error handling, profile fields and entitlements are covered in Connect your users.

Android

connectUser is a suspending function that returns an OctopusResult:

import com.octopuscommunity.sdk.domain.model.ClientUser
import com.octopuscommunity.sdk.domain.network.OctopusResult

viewModelScope.launch {
    val result = OctopusSDK.connectUser(
        user = ClientUser(userId = user.id),
        tokenProvider = { yourBackend.fetchOctopusToken(user.id) },
    )
    if (result !is OctopusResult.Success) {
        // The connection was refused: see Connect your users
    }
}

iOS

do {
    try await octopus.connectUser(
        ClientUser(userId: user.id, profile: .init(nickname: user.name)),
        tokenProvider: { try await yourBackend.fetchOctopusToken(userId: user.id) }
    )
} catch {
    // error is an OctopusConnectUserError: see Connect your users
}

Flutter

final result = await OctopusSDK().connectUser(
  userId: user.id,
  nickname: user.name,
  tokenProvider: () => yourBackend.fetchOctopusToken(user.id),
);
if (result is! OctopusSuccess) {
  // The connection was refused: see Connect your users
}

React Native

Register the token provider once, in a component that stays mounted, then connect the user:

import { connectUser, useUserTokenProvider } from '@octopus-community/react-native';

useUserTokenProvider(() => yourBackend.fetchOctopusToken(user.id));

await connectUser({ userId: user.id, profile: { username: user.name } });
// connectUser rejects when the connection is refused: see Connect your users

Unity

using System.Threading.Tasks;

public async void OnPlayerSignedIn(string userId, string nickname)
{
    await OctopusSDK.ConnectUser(userId, nickname, null, null, FetchOctopusToken);
}

// May run on a background thread: use System.Net.Http, not UnityWebRequest.
static Task<string> FetchOctopusToken() => yourBackend.FetchOctopusTokenAsync();

---

5. Run and verify

Run your app and open the community from your entry point. You should see the community home feed with the posts of your sandbox community. Before connectUser, trying to post opens your sign-in flow; after it, the member can post, comment and react under their own profile.

If it does not work:

• The feed stays empty or shows an error. Check that the API key is the sandbox key of the community you expect and that initialization runs before the community opens.
• The member stays a guest after connectUser. The token was refused: your backend must sign it with the secret of the same community as the API key. Read the error returned by connectUser (Connect your users).
• The app crashes when the first community screen opens. A platform requirement of 1. Install the SDK is missing: check the notes in your platform tab.

Next steps

• Connect your users: profile fields your app owns, errors, entitlements and guest sessions.
• Configuration and lifecycle: deep links, custom API server and SDK lifecycle.
• Display the community: tabs, embedded views and bottom sheets.
• Theming: colors, fonts and logo.
• Sample apps: complete integrations to run and read.