Official SDK Integration

Add byStrate.com stories to your app with one production SDK setup.

Configure the SDK once, render story placements where they belong, and keep user identity in sync so analytics, widget votes, and billing events stay accurate.

Open Dashboard Contact Engineering

Production Endpoint

https://bystrate.com

Base path: /sdk/v1

Required header: X-StoryOS-SDK-Key

Environment value: PRODUCTION

Native Apps

Use the SwiftUI and Android Compose SDKs for production mobile placements.

Web SDK

Use @strate/web-sdk when the same story experience belongs on a web surface.

Public SDK Key

The SDK key is safe in client apps. Keep private dashboard API keys server-side.

Before You Integrate

Prepare dashboard data first.

The SDK only renders published content for active placements. Set up these records before testing a production build.

Create an app in the byStrate.com dashboard.

Copy the app key and public SDK key from Apps.

Create at least 1 active placement, for example home_top.

Publish a story group to the target environment.

Install

Use the private byStrate.com package provided during onboarding.

Public distribution coordinates are intentionally not listed here until your workspace receives its package access.

iOS / SwiftUI

Add the private Swift Package URL from onboarding, then import the current package product.

import storyos

Android / Compose

Add the private Gradle/Maven package from onboarding, then import the SDK namespace.

import com.storyos.sdk.core.StorySDK

Web

Install the published web package for browser placements.

npm install @strate/web-sdk

Configure

Initialize the SDK once during app startup.

Use the app key and SDK key from the dashboard. The production environment resolves to the byStrate.com API endpoint.

iOS / Swift

import storyos

@main
struct RetailApp: App {
    init() {
        let config = StoryConfiguration(
            sdkKey: "sdk_live_xxxxxxxxxxxx",
            appKey: "app_xxxxxxxxxxxx",
            environment: .production
        )

        StorySDK.shared.configure(config)
    }

    var body: some Scene {
        WindowGroup {
            HomeView()
        }
    }
}

Android / Kotlin

class RetailApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        StorySDK.configure(
            configuration = StoryConfiguration(
                sdkKey = "sdk_live_xxxxxxxxxxxx",
                appKey = "app_xxxxxxxxxxxx",
                environment = StoryEnvironment.PRODUCTION
            ),
            context = this
        )
    }
}

Web / TypeScript

import { StorySDK, StoryWidget } from "@strate/web-sdk";

StorySDK.configure({
  sdkKey: "sdk_live_xxxxxxxxxxxx",
  appKey: "app_xxxxxxxxxxxx",
  environment: "PRODUCTION",
});

const widget = new StoryWidget();
widget.mount(document.getElementById("story-bar"), "home_top");

Render

Render a placement by key.

A placement key maps a position in your app to published story groups in the dashboard.

iOS / SwiftUI

import SwiftUI
import storyos

struct HomeView: View {
    var body: some View {
        StoryBarView(placementKey: "home_top")
    }
}

Android / Compose

@Composable
fun HomeScreen() {
    StoryBarView(placementKey = "home_top")
}

Identity

Update the SDK session when user identity changes.

This keeps votes, analytics events, and usage metering tied to the correct app and user session.

Session Updates

// iOS
StorySDK.shared.updateSession(
    appId: "retail-ios",
    bundleId: Bundle.main.bundleIdentifier,
    userId: "user_123"
)

// Android
StorySDK.updateSession(
    appId = "retail-android",
    bundleId = context.packageName,
    userId = "user_123"
)

// Web
StorySDK.updateSession("retail-web", "com.example.web", "user_123");

Production Checklist

Verify delivery before release.

Run through these checks before shipping a production app build that includes stories.

Use production keys only in production app builds.
Confirm StoryEnvironment.PRODUCTION or environment: "PRODUCTION" is selected.
Call updateSession after login, logout, account switch, or app identity changes.
Verify the story bar renders nothing, not an error panel, when a placement is empty.
Trigger one story open and one CTA click, then confirm analytics and billing events arrive.

REST Contract

The SDK talks to these public runtime endpoints.

You usually do not call these endpoints directly from product code; they are listed here for network review and integration debugging.

Method	Path	Purpose
GET	/sdk/v1/apps/{appKey}/placements/{placementKey}/stories	Fetch the latest published story payload for one placement.
POST	/sdk/v1/apps/{appKey}/story-items/{storyItemId}/vote	Record a poll or quiz vote from a SDK widget.
POST	/sdk/v1/events	Track SDK analytics and usage-metering events.

Authentication

Every SDK runtime request sends X-StoryOS-SDK-Key. Do not replace it with a private dashboard API key.

Environment

The SDK sends environment=PRODUCTION or environment=STAGING as a query value when fetching stories.

Headers

Optional identity headers are X-StoryOS-AppId, X-StoryOS-BundleId, and X-StoryOS-UserId.