Read the quickstart

Quickstart

This guide takes you from an empty project to the first real session in the console. It takes about fifteen minutes and does not change how you build or release the app.

1. Create a project and get a key

In the console, open Projects and choose New project. Pick the platform and the home region. The home region decides where your data is stored and which collector the SDK will talk to; it cannot be changed later, so pick the region closest to most of your users or the one your data residency rules require.

When the project is created, the settings page shows two values you need:

  • Project key, for example 4f9c2e1b8a7d63e0. Put it in the SDK configuration.
  • Collector host. You do not have to configure it; the SDK receives it during the first upload handshake. It is shown so you can allow it in a network security policy or verify reachability from a device.

Project keys are write-only. They can send telemetry and nothing else, so shipping them inside the app is expected. If a key is ever misused, rotate it from the same page; the old key stays valid for 24 hours.

2. Add the SDK

Pick your platform. Each guide covers the package manager, initialisation and the integration points for the HTTP client and navigation library you use.

iOSSwift Package Manager or XCFramework AndroidGradle plugin and library React Nativenpm package with native modules Flutterpub.dev package with platform channels

3. Start the SDK

Call start once, as early as possible in the process. On iOS that is the App initialiser or application(_:didFinishLaunchingWithOptions:); on Android it is Application.onCreate, or nothing at all if you keep the automatic initialiser enabled.

Swift
import Gatepost

Gatepost.start(projectKey: "4f9c2e1b8a7d63e0")
Kotlin
import org.mustgate.gatepost.Gatepost

Gatepost.start(this, "4f9c2e1b8a7d63e0")

With the defaults, the SDK records app start, screens, HTTP requests through the platform client, slow and frozen frames, crashes and ANRs, and samples 100% of sessions. You can change any of these later from the console without shipping a build; see the sampling rules.

4. Verify the first session

  1. Run the app on a device or emulator and use it for a few seconds.
  2. Put the app in the background. The SDK uploads the batch within 30 seconds, or immediately when the session ends.
  3. In the console, open Live sessions. The session appears with the device model, OS version, release and the screens you visited.

If nothing arrives after a minute:

  • Check the key. A wrong key is answered with 401 {"error":"invalid project key"}, which the SDK logs at warning level.
  • Open https://<collector-host>/diagnostics in the device browser. The page runs a reachability and throughput check from that network and shows the region the device is talking to.
  • On Android, confirm the app has the INTERNET permission and that a network security config does not block the collector host.
  • On iOS, make sure the SDK is started before any URLSession is created if you want the first requests instrumented.

5. Next steps

  • Name your screens if automatic names are not readable enough. See screens on iOS and screens on Android.
  • Upload symbol files so crashes are readable: dSYM on iOS, R8 mapping on Android.
  • Add a custom trace around the operation users complain about most. Checkout, search and first content load are the usual suspects.
  • Set an alert on cold start p95 per release, so the next regression is a notification rather than a review.