Sample apps
Each platform has a sample app that shows a complete integration: initialization, SSO, navigation, theming and more. Run it with your own API key to see the community working before you integrate it in your app.
Before you begin
- An API key for a sandbox community. Request one from the form on octopuscommunity.com.
- To sign users in with SSO, a way to get a user token: either your community's token secret, used by some samples to sign a JWT locally, or a JWT from your backend. See Generate a signed JWT.
- The toolchain of your platform: see Requirements.
Some samples sign the SSO JWT inside the app with your community's token secret, only to make the demo self-contained. Never put this secret in an app you ship: anyone could extract it and sign in as any user. In your app, the JWT always comes from your backend.
Which sample shows what
| Platform | Repository | What it covers |
|---|---|---|
| Android | octopus-sdk-android | One app with navigation, theming, SSO, bridges and push notification scenarios. |
| iOS | octopus-sdk-swift | A Scenarios tab (SSO, theming, bridges, events and more), the embedded Community tab, and Settings. |
| Flutter | octopus-sdk-flutter | The example app, with SSO and the reactive APIs. |
| React Native | octopus-sdk-react-native | The example app, whose Scenarios tab walks through most of the reactive and analytics APIs. |
| Unity | octopus-sdk-unity | The UnityExample project, and importable samples for push notifications and groups. |
Run the sample
- Android
- iOS
- Flutter
- React Native
- Unity
The sample module is the canonical showcase: Configuration, Scenarios, Community, Settings and a Debug console. Scenarios cover navigation, theming, SSO, bridge content and push in one app. It needs JDK 17 and Android SDK 36, or Android Studio.
-
Clone the repository and add your API key to
local.propertiesat its root:git clone https://github.com/Octopus-Community/octopus-sdk-android.git && cd octopus-sdk-androidecho "OCTOPUS_API_KEY=YOUR_API_KEY" >> local.properties -
To sign users in with SSO, also add your community's token secret. The sample uses it to sign the JWT locally:
OCTOPUS_SSO_CLIENT_USER_TOKEN_SECRET=YOUR_TOKEN_SECRET -
Install the demo flavor:
./gradlew :sample:installDemoDebug
The demo flavor lets you pick a server and a sandbox API key; prod uses the production server.
The app's entry point is MainActivity.kt.
Since 1.15.0, the in-memory repositories in com.octopuscommunity.sdk.test.di.octopusTestModule keep created/deleted posts consistent across feeds, groups and profiles, separate connected users' feeds, and filter blocked authors from posts, featured comments, comments and replies. Fixtures include an unvoted poll, expandable text and video metadata (playback is not guaranteed). Repository seeds reuse the ids of MockPosts.default, withPoll, withClientObject, withComment, MockComments.default and MockReplies.default, but normalize their displayed state: read it from the repositories rather than assuming preview mocks are identical. Fetching other comment and reply feeds still generates items.
The sample lives in the same repository as the SDK.
-
Clone the repository and create your secrets file from the template:
git clone https://github.com/Octopus-Community/octopus-sdk-swift.git && cd octopus-sdk-swiftcp Sample/OctopusSample/Config/secrets.placeholder.xcconfig Sample/OctopusSample/Config/secrets.xcconfig -
In
secrets.xcconfig, setOCTOPUS_API_KEYto your API key. To connect a user, also setCLIENT_USER_TOKEN_SECRETto your community's token secret: the sample uses it to sign the JWT locally. -
Open
Sample/OctopusSample.xcworkspace. InOctopusSDKProvider, uncomment the call ininitializeSDKthat matches the profile fields your app manages: none (the active one), all, or some of them. -
Run the
OctopusSamplescheme. Connect a user from the SSO scenario in the Scenarios tab, which also lists the other scenarios. The Community tab shows the community embedded in a tab.
-
Clone the repository and install the dependencies of the example:
git clone https://github.com/Octopus-Community/octopus-sdk-flutter.git && cd octopus-sdk-flutter/exampleflutter pub get -
Run the example with your credentials.
OCTOPUS_USER_IDandOCTOPUS_USER_TOKEN, a JWT from your backend, are needed only to try SSO:flutter run \--dart-define=OCTOPUS_API_KEY=YOUR_API_KEY \--dart-define=OCTOPUS_USER_ID=YOUR_TEST_USER_ID \--dart-define=OCTOPUS_USER_TOKEN=YOUR_JWT
The app launches without a key too: the Home tab then reports an initialization error.
-
Clone the repository and install the dependencies from its root, which also installs the example:
git clone https://github.com/Octopus-Community/octopus-sdk-react-native.git && cd octopus-sdk-react-nativeyarn -
Create your environment file from the template, then set
OCTOPUS_COMMUNITY_API_KEYin it. To try SSO, also setOCTOPUS_SSO_USER_IDandOCTOPUS_SSO_USER_TOKEN, a JWT from your backend:cp example/.env.dist example/.env -
Build and run the example:
yarn example android# On iOS, install the pods first:yarn example ios:pod && yarn example ios
- Full sample: clone octopus-sdk-unity and open the
UnityExamplefolder in Unity. Create a configuration with Assets > Create > Octopus Example Config, set your API key in it, then build for Android or iOS. - Focused samples: in your own project, open Window > Package Manager > Octopus SDK for Unity > Samples and import Push Notifications Example or Groups Example.
To try the SDK in the Editor without a device build, see Unity Editor Mock Mode.
Next steps
- Quickstart: integrate the SDK in your own app.
- Connect your users: replace the sample's local JWT signing with your backend.
- Generate a signed JWT: the backend route that signs user tokens.