Reset API in Mobile SDKs

Learn about the reset API call in the Android (Kotlin) and iOS (Swift) SDKs.

6 minute read

This guide explains how to use the reset API in the RudderStack Android (Kotlin) and iOS (Swift) SDKs.

Overview

The RudderStack Android (Kotlin) and iOS (Swift) SDKs provide a reset API that lets you clear the persisted data, for example, user ID and traits.

The SDK also does the following once you call the reset API:

Generates a new anonymousId (default behavior)
If session tracking is enabled, clears the current sessionId and generates a new one.

If a mobile device mode integration plugin is present, then calling the reset API also triggers the integration’s reset API — provided it is supported.

The reset API supports the following invocations:

Default behavior: Clears all persisted user data
Selective reset: Choose specific data points to reset while preserving others

Default behavior

By default, calling the reset API clears all persisted user data including user ID and traits, refreshes session information, and generates a new anonymous ID.

kotlin

analytics.reset()

The corresponding Java snippet is shown below:

java

analytics.reset();

swift

analytics.reset()

The corresponding Objective-C snippet is shown below:

objectivec

[analytics reset];

Selective reset

You can also use the reset API to choose which specific data components to reset while preserving others. This way, you have granular control over each component — you can regenerate the anonymous ID, clear the user ID, clear traits, or refresh session information, or preserve any of these values as per your requirement.

To perform a selective reset, the SDKs provide a options parameter that accepts a ResetOptions object with the following structure:

kotlin

val options = ResetOptions(
  entries = ResetEntries(
    anonymousId = true,
    userId = true,
    traits = true,
    session = true
  )
)
analytics.reset(options)

The corresponding Java snippet is shown below:

java

ResetEntriesBuilder entriesBuilder = new ResetEntriesBuilder()
  .setAnonymousId(true)
  .setUserId(true)
  .setTraits(true)
  .setSession(true);
ResetOptionsBuilder optionsBuilder = new ResetOptionsBuilder()
  .setEntries(entriesBuilder.build());
analytics.reset(optionsBuilder.build());

swift

analytics.reset(options: ResetOptions(
  entries: ResetEntries(
    anonymousId: true,
    userId: true,
    traits: true,
    session: true
  )
))

The corresponding Objective-C snippet is shown below:

objectivec

RSSResetEntriesBuilder *entriesBuilder = [RSSResetEntriesBuilder new];
[entriesBuilder setAnonymousIdResetEntry:YES];
[entriesBuilder setUserIdResetEntry:YES];
[entriesBuilder setTraitsResetEntry:YES];
[entriesBuilder setSessionResetEntry:YES];

RSSResetOptionsBuilder *optionsBuilder = [RSSResetOptionsBuilder new];
[optionsBuilder setEntries:[entriesBuilder build]];

[analytics resetWithOptions:[optionsBuilder build]];

`entries` parameters

The following table describes the parameters accepted by the entries object of ResetOptions:

Parameter	Description	Default value
`anonymousId`	Resets the anonymous user ID.	`true`
`userId`	Resets the persisted user ID.	`true`
`traits`	Resets the persisted user traits.	`true`
`session`	Resets the current session information.	`true`

All entries in the ResetOptions.entries object are optional. If you do not specify any entry, the SDK sets its default value as described in the above table.

Examples

This section provides the following examples of performing a selective reset using the reset API:

Reset all data except session information
Reset only session information
Reset only user ID and traits

Reset all data except session information

kotlin

analytics.reset(ResetOptions(
  entries = ResetEntries(
    anonymousId = true,
    userId = true,
    traits = true,
    session = false
  )
))

The corresponding Java snippet is shown below:

java

ResetEntriesBuilder entriesBuilder = new ResetEntriesBuilder()
  .setAnonymousId(true)
  .setUserId(true)
  .setTraits(true)
  .setSession(false);
ResetOptionsBuilder optionsBuilder = new ResetOptionsBuilder()
  .setEntries(entriesBuilder.build());
analytics.reset(optionsBuilder.build());

swift

analytics.reset(options: ResetOptions(
  entries: ResetEntries(
    anonymousId: true,
    userId: true,
    traits: true,
    session: false
  )
))

The corresponding Objective-C snippet is shown below:

objectivec

RSSResetEntriesBuilder *entriesBuilder = [RSSResetEntriesBuilder new];
[entriesBuilder setAnonymousIdResetEntry:YES];
[entriesBuilder setUserIdResetEntry:YES];
[entriesBuilder setTraitsResetEntry:YES];
[entriesBuilder setSessionResetEntry:NO];

RSSResetOptionsBuilder *optionsBuilder = [RSSResetOptionsBuilder new];
[optionsBuilder setEntries:[entriesBuilder build]];

[analytics resetWithOptions:[optionsBuilder build]];

Reset only session information

kotlin

analytics.reset(ResetOptions(
  entries = ResetEntries(
    anonymousId = false,
    userId = false,
    traits = false,
    session = true
  )
))

The corresponding Java snippet is shown below:

java

ResetEntriesBuilder entriesBuilder = new ResetEntriesBuilder()
  .setAnonymousId(false)
  .setUserId(false)
  .setTraits(false)
  .setSession(true);
ResetOptionsBuilder optionsBuilder = new ResetOptionsBuilder()
  .setEntries(entriesBuilder.build());
analytics.reset(optionsBuilder.build());

swift

analytics.reset(options: ResetOptions(
  entries: ResetEntries(
    anonymousId: false,
    userId: false,
    traits: false,
    session: true
  )
))

The corresponding Objective-C snippet is shown below:

objectivec

RSSResetEntriesBuilder *entriesBuilder = [RSSResetEntriesBuilder new];
[entriesBuilder setAnonymousIdResetEntry:NO];
[entriesBuilder setUserIdResetEntry:NO];
[entriesBuilder setTraitsResetEntry:NO];
[entriesBuilder setSessionResetEntry:YES];

RSSResetOptionsBuilder *optionsBuilder = [RSSResetOptionsBuilder new];
[optionsBuilder setEntries:[entriesBuilder build]];

[analytics resetWithOptions:[optionsBuilder build]];

Reset only user ID and traits

kotlin

analytics.reset(ResetOptions(
  entries = ResetEntries(
    anonymousId = false,
    userId = true,
    traits = true,
    session = false
  )
))

The corresponding Java snippet is shown below:

java

ResetEntriesBuilder entriesBuilder = new ResetEntriesBuilder()
  .setAnonymousId(false)
  .setUserId(true)
  .setTraits(true)
  .setSession(false);
ResetOptionsBuilder optionsBuilder = new ResetOptionsBuilder()
  .setEntries(entriesBuilder.build());
analytics.reset(optionsBuilder.build());

swift

analytics.reset(options: ResetOptions(
  entries: ResetEntries(
    anonymousId: false,
    userId: true,
    traits: true,
    session: false
  )
))

The corresponding Objective-C snippet is shown below:

objectivec

RSSResetEntriesBuilder *entriesBuilder = [RSSResetEntriesBuilder new];
[entriesBuilder setAnonymousIdResetEntry:NO];
[entriesBuilder setUserIdResetEntry:YES];
[entriesBuilder setTraitsResetEntry:YES];
[entriesBuilder setSessionResetEntry:NO];

RSSResetOptionsBuilder *optionsBuilder = [RSSResetOptionsBuilder new];
[optionsBuilder setEntries:[entriesBuilder build]];

[analytics resetWithOptions:[optionsBuilder build]];

Implicit reset via `identify`

The identify API internally calls reset() when the userId changes. This is an implicit reset — it uses default ResetOptions (all entries reset to true). See the following scenarios for more information:

Scenario	Reset triggered?	What is reset
`identify` on anonymous user (no prior `userId`)	No	Nothing
`identify` with the same `userId`	No	Nothing
`identify` with a different `userId` (User A > User B)	Yes	`anonymousId` regenerated `userId` cleared `traits` cleared `sessionId` refreshed

You cannot pass custom ResetOptions to the implicit reset. To preserve specific entries (for example, to keep the session intact during a user switch), call reset explicitly with your desired options before calling identify.

Why this works: The explicit reset call clears the userId (since userId = true). When you call identify subsequently, the SDK sees that no previous userId is set - so it treats this as an anonymous-to-identified transition and skips the implicit reset entirely. This way, any entries you chose to preserve in the explicit reset (for example, session = false) remain untouched.

kotlin

// Preserve session while switching users

analytics.reset(ResetOptions(
    entries = ResetEntries(
        anonymousId = true,
        userId = true, // Should be set to `true` — otherwise the approach will not work.
        traits = true,
        session = false  // Preserve session
    )
))
analytics.identify(userId = "new-user-id")

The corresponding Java snippet is shown below:

java

// Preserve session while switching users

ResetEntriesBuilder entriesBuilder = new ResetEntriesBuilder()
  .setAnonymousId(true)
  .setUserId(true) // Should be set to true — otherwise this approach won't work.
  .setTraits(true)
  .setSession(false);  // Preserve session
ResetOptionsBuilder optionsBuilder = new ResetOptionsBuilder()
  .setEntries(entriesBuilder.build());
analytics.reset(optionsBuilder.build());
analytics.identify("new-user-id");

swift

// Preserve session while switching users

analytics.reset(options: ResetOptions(
    entries: ResetEntries(
        anonymousId: true,
        userId: true, // Should be set to `true` — otherwise the approach will not work.
        traits: true,
        session: false  // Preserve session
    )
))
analytics.identify(userId: "new-user-id")

The corresponding Objective-C snippet is shown below:

objectivec

// Preserve session while switching users

RSSResetEntriesBuilder *entriesBuilder = [RSSResetEntriesBuilder new];
[entriesBuilder setAnonymousIdResetEntry:YES];
[entriesBuilder setUserIdResetEntry:YES]; // Should set to YES — otherwise this approach won't work.
[entriesBuilder setTraitsResetEntry:YES];
[entriesBuilder setSessionResetEntry:NO];  // Preserve session

RSSResetOptionsBuilder *optionsBuilder = [RSSResetOptionsBuilder new];
[optionsBuilder setEntries:[entriesBuilder build]];

[analytics resetWithOptions:[optionsBuilder build]];
[analytics identify:@"new-user-id"];

Reset API in Mobile SDKs

Overview

Default behavior

Selective reset

entries parameters

Examples

Reset all data except session information

Reset only session information

Reset only user ID and traits

Implicit reset via identify

Questions? Let's figure it out together.

`entries` parameters

Implicit reset via `identify`