End-to-End Walkthrough: RudderTyper v2 with Rudder CLI Beta

This tutorial shows you how to use RudderTyper v2 via the Rudder CLI tool to:

• Generate type-safe TypeScript, Kotlin, or Swift bindings from your Tracking Plans
• Install the generated bindings in your web (JavaScript), Android, JVM, or iOS application
• Customize the generated code with platform-specific options
• Instrument your application using the generated bindings

Prerequisites

• Rudder CLI tool (rudder-cli) installed locally
• A workspace-level Service Access Token or Personal Access Token with read access to the Tracking Plan you want to use
• An existing Tracking Plan in your RudderStack workspace

1. Authenticate Rudder CLI

Run the following command and enter your access token when prompted:

rudder-cli auth login

2. Identify your Tracking Plan ID

To generate type-safe bindings, first identify the Tracking Plan you want to generate bindings against. Run the following command:

rudder-cli workspace tracking-plans list

The above command displays an interactive table with all available Tracking Plans in your workspace. The output shows a list of Tracking Plans on the left, and selecting a Tracking Plan displays its details on the right, including the plan’s name, description, and current version.

Use this information to identify the Tracking Plan you want to use and copy its ID, as highlighted below:

Navigate using the arrow keys if you have more Tracking Plans than what can be displayed, and exit the view by pressing the Escape key.

3. Generate bindings

Using the Tracking Plan ID, run the following command for your target platform:

rudder-cli typer generate --platform=typescript --tracking-plan-id=<TRACKING_PLAN_ID> -o <OUTPUT_DIRECTORY>

rudder-cli typer generate --platform=kotlin --tracking-plan-id=<TRACKING_PLAN_ID> -o <OUTPUT_DIRECTORY>

rudder-cli typer generate --platform=swift --tracking-plan-id=<TRACKING_PLAN_ID> -o <OUTPUT_DIRECTORY>

The above command generates bindings for the platform indicated by the --platform flag (typescript, kotlin, or swift), for the Tracking Plan indicated by the --tracking-plan-id flag, and stores the generated files in the directory indicated by the -o flag.

Note that:

• --platform and --tracking-plan-id are required flags
• -o is optional and defaults to the current working directory if omitted
• You can view all available options by running rudder-cli typer generate -h

See the RudderTyper v2 Command Reference for more information on the above command and the supported flags.

4. Install bindings in your application

src/main/kotlin/com/rudderstack/ruddertyper

5. Optional: Customize the generated code

Depending on the platform, RudderTyper supports platform-specific options that customize the generated code.

You can provide these options to the rudder-cli typer generate command using one or more --option flags that accept a key-value pair separated by =.

To view available options for your platform, run:

rudder-cli typer options --platform=typescript

rudder-cli typer generate --platform=typescript --tracking-plan-id=<TRACKING_PLAN_ID> --option outputFileName=Events.ts

rudder-cli typer options --platform=kotlin

decoding="async" loading="lazy" class="img-shortcode"/>

rudder-cli typer generate --platform=kotlin --tracking-plan-id=<TRACKING_PLAN_ID> --option packageName=com.example.package

rudder-cli typer generate --platform=kotlin --tracking-plan-id=<TRACKING_PLAN_ID> --option composeImmutable=true

rudder-cli typer options --platform=swift

6. Instrument your application

After installing the generated files in your application’s source folders, you can use them as a wrapper over the RudderStack SDK.

Assuming your SDK instance is initialized and available through a variable called analytics, instantiate and use the RudderTyper wrapper by passing the analytics object as an argument:

import { RudderAnalytics } from "@rudderstack/analytics-js";
import { RudderTyper } from "./RudderTyper";

// Example setup of the SDK
const analytics = new RudderAnalytics();
analytics.load("<WRITE_KEY>", "<DATA_PLANE_URL>");

// Setup of RudderTyper bindings
const typer = new RudderTyper(analytics);

import com.rudderstack.ruddertyper.RudderAnalytics
import com.rudderstack.sdk.kotlin.android.Analytics
import com.rudderstack.sdk.kotlin.android.Configuration

// Example setup of the SDK
val configuration = Configuration(
    writeKey = BuildConfig.WRITE_KEY,
    application = this,
    dataPlaneUrl = BuildConfig.DATA_PLANE_URL,
    flushPolicies = listOf(
        CountFlushPolicy(1)
    )
)

analytics = Analytics(configuration)

// Setup of RudderTyper bindings
val typer = com.rudderstack.ruddertyper.RudderAnalytics(analytics)

import RudderStackAnalytics

// Example setup of the SDK
let config = Configuration(
    writeKey: "<WRITE_KEY>",
    dataPlaneUrl: "<DATA_PLANE_URL>"
)

let analytics = Analytics(configuration: config)

// Setup of RudderTyper bindings
let rudderTyper = RudderTyperAnalytics(analytics: analytics)

Use the generated bindings

The wrapper object exposes methods that correspond to the events in your Tracking Plan.

For identify, screen, and group event types added as rules to the Tracking Plan, the wrapper exposes methods with signatures identical to those exposed by the SDK, except with strongly typed properties or trait arguments. For TypeScript, which targets the web-based JavaScript SDK, the wrapper exposes a page method instead of screen.

For example, an identify event with a single name property added to its traits through the Tracking Plan:

typer.identify("1hKOmRA4GRlm", {
  name: "Alex Keener"
})

import com.rudderstack.ruddertyper.IdentifyTraits

typer.identify(
  userId = "1hKOmRA4GRlm",
  traits = IdentifyTraits(
    name = "Alex Keener"
  )
)

rudderTyper.identify(
    userId: "1hKOmRA4GRlm",
    traits: IdentifyTraits(name: "Alex Keener")
)

Similarly, track events added as rules in a Tracking Plan correspond to methods named with a track prefix followed by a CamelCase version of the event’s name. For example, you can send an event named User Login using:

typer.trackUserLogin({
  // ... properties defined in your Tracking Plan
})

typer.trackUserLogin(
  properties = TrackUserLoginProperties(
    // ... properties defined in your Tracking Plan
  )
)

rudderTyper.trackUserLogin(
    properties: TrackUserLoginProperties(
        // ... properties defined in your Tracking Plan
    )
)

Next steps

• See the RudderTyper v2 Command Reference for detailed information about all available CLI commands and parameters
• See the Limitations section for more information on the limitations of the generated bindings