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.
info
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

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.

analytics.reset()

The corresponding Java snippet is shown below:

analytics.reset();

analytics.reset()

The corresponding Objective-C snippet is shown below:

[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:

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

The corresponding Java snippet is shown below:

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

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

The corresponding Objective-C snippet is shown below:

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:

ParameterDescriptionDefault value
anonymousIdResets the anonymous user ID.true
userIdResets the persisted user ID.true
traitsResets the persisted user traits.true
sessionResets the current session information.true
info
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

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

The corresponding Java snippet is shown below:

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

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

The corresponding Objective-C snippet is shown below:

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

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

The corresponding Java snippet is shown below:

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

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

The corresponding Objective-C snippet is shown below:

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

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

The corresponding Java snippet is shown below:

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

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

The corresponding Objective-C snippet is shown below:

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)NoNothing
identify with the same userIdNoNothing
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.

// 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:

// 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");

// 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:

// 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"];

Questions? We're here to help.

Join the RudderStack Slack community or email us for support

Slack Join now → Email Reach out →