Skip to content
Docs menu Operate

Migrate from Segment

Keep your Segment tracking calls. Change the write key and the host your Segment libraries send to, and events land in Sfere

On this page

Sfere accepts the Segment event format, so your existing track, identify, page and group calls keep working. For each library you change two things: the write key, which becomes a Sfere key from the source’s Settings tab, and the host, which becomes events.sfere.io. The mobile libraries need one extra setting, shown below.

Starting fresh? The Sfere SDKs are built for this and need none of these settings.

Before you start#

  1. Create a source in Sfere for each Segment source you are moving: a website source for analytics.js, an app source for each mobile app, and a server source for backend libraries.
  2. Create the right key for each: a browser key for websites and apps, a server key for backend libraries. See Write keys.

Websites: analytics.js#

Use the npm package @segment/analytics-next, version 1.84.0 or newer. The classic cdn.segment.com snippet cannot be pointed at Sfere; replace it with the npm package or with the Sfere JavaScript SDK.

analytics.jsJavaScript
import { AnalyticsBrowser } from "@segment/analytics-next";

const writeKey = "YOUR_BROWSER_KEY";

export const analytics = AnalyticsBrowser.load({
  writeKey,
  cdnSettings: {
    integrations: {
      "Segment.io": {
        apiKey: writeKey,
        apiHost: "events.sfere.io/v1/batch",
        protocol: "https",
        addBundledMetadata: false,
        deliveryStrategy: { strategy: "batching", config: { size: 10, timeout: 5000 } },
      },
    },
    plan: {
      track: { __default: { enabled: true } },
      identify: { __default: { enabled: true } },
      group: { __default: { enabled: true } },
    },
    metrics: { sampleRate: 0 },
  },
});

The settings are passed inline, so the library does not fetch them from Segment, and metrics.sampleRate: 0 stops it reporting usage metrics. In TypeScript you may need to cast cdnSettings to CDNSettings.

Your anonymous IDs and user IDs carry over: analytics.js keeps them in ajs_* cookies and local storage that do not depend on the write key.

iOS: analytics-swift#

Set both hosts, and set defaultSettings too. Without it, if the first settings request fails, the library falls back to Segment’s own host.

AppDelegate.swiftSwift
import Segment

Telemetry.shared.enable = false
let writeKey = "YOUR_BROWSER_KEY"

let analytics = Analytics(configuration: Configuration(writeKey: writeKey)
    .apiHost("events.sfere.io/v1/batch")
    .cdnHost("events.sfere.io/v1")
    .defaultSettings(Settings(writeKey: writeKey, apiHost: "events.sfere.io/v1/batch")))

Android: analytics-kotlin#

The same rule applies: set both hosts and defaultSettings.

MainApplication.ktKotlin
Telemetry.enable = false
val writeKey = "YOUR_BROWSER_KEY"

val analytics = Analytics(writeKey, applicationContext) {
    apiHost = "events.sfere.io/v1/batch"
    cdnHost = "events.sfere.io/v1"
    defaultSettings = Settings(integrations = buildJsonObject {
        put("Segment.io", buildJsonObject {
            put("apiKey", writeKey)
            put("apiHost", "events.sfere.io/v1/batch")
        })
    })
}

The mobile libraries store IDs per write key, so after the switch each app install starts with a new anonymous ID, and events still queued under the old key are not sent. Call identify again when a signed-in customer opens the app.

Server libraries#

Use a server key. Ruby and Java default to a path Sfere does not serve, so set it explicitly.

Library Configuration
Node.js (@segment/analytics-node) new Analytics({ writeKey: "YOUR_SERVER_KEY", host: "https://events.sfere.io" })
Python (analytics-python) analytics.write_key = "YOUR_SERVER_KEY" and analytics.host = "https://events.sfere.io"
Go (analytics-go) analytics.NewWithConfig("YOUR_SERVER_KEY", analytics.Config{Endpoint: "https://events.sfere.io"})
PHP (analytics-php) Segment::init("YOUR_SERVER_KEY", ["host" => "events.sfere.io"])
Ruby (analytics-ruby) Segment::Analytics.new(write_key: "YOUR_SERVER_KEY", host: "events.sfere.io", path: "/v1/batch")
Java (analytics-java) Analytics.builder("YOUR_SERVER_KEY").setUploadURL("https://events.sfere.io/v1/batch").build()

Calling Segment’s HTTP Tracking API directly? Send batches to https://events.sfere.io/v1/batch. The single-call paths /v1/track, /v1/identify and /v1/page are not available; use /api/s/s2s/{type} instead. See HTTP API.

What does not carry over#

  • Destinations. Segment’s destinations, device-mode integrations, Protocols tracking plans, Functions and Engage do not move with the library. Connect destinations in Sfere with pipes and rebuild transformations as functions.
  • Extra fields. Segment’s libraries add _metadata and integrations to events, and each becomes a warehouse column. Drop them with a transform function if you do not need them.

Confirm the switch#

Deploy the change, then open Live events for each new source and check that events arrive. A wrong key on the single-event endpoint is not reported as an error, so check Live events rather than relying on HTTP status codes.