# Alias API in Mobile SDKs


This guide explains how to use the `alias` API in the [Android (Kotlin)]({{< ref "sources/event-streams/sdks/kotlin-sdk/" >}}) and [iOS (Swift)]({{< ref "sources/event-streams/sdks/swift-sdk/" >}}) SDKs.

## Overview

The RudderStack Android (Kotlin) and iOS (Swift) SDKs provide an [`alias`]({{< ref "event-spec/standard-events/alias.md" >}}) API that lets you merge different identities of a known user.

Note that:

- You can use the `alias` event only for merging user identities. It **does not** update the user’s traits or other common properties.
- RudderStack supports sending `alias` events only to certain downstream destinations. See the [destination-specific documentation]({{< ref "destinations/streaming-destinations/" >}}) for more details.

## Android (Kotlin)

The `alias` method definition in the Android (Kotlin) SDK is as follows:

{{< tabs tabTotal="2" >}}
{{% tab tabName="Default invocation" %}}
```kotlin
analytics.alias(
    newId = "<newId>",
    previousId = "<previousId>",
    options = RudderOption()
)
```

The corresponding Java snippet is shown below:

```java
analytics.alias("<newId>", "<previousId>", new RudderOption());
```
{{% /tab %}}
{{% tab tabName="Alternate invocations" %}}
```kotlin
// Alias event with newId
analytics.alias(newId = "<newId>")

// Alias event with newId and previousId
analytics.alias(
    newId = "<newId>",
    previousId = "<previousId>"
)

// Alias event with newId and options
analytics.alias(
    newId = "<newId>",
    options = RudderOption(
        customContext = buildJsonObject {
            put("key", "value")
        },
        integrations = buildJsonObject {
            put("Amplitude", true)
            put("INTERCOM", buildJsonObject {
                put("lookup", "phone")
            })
        },
        externalIds = listOf(
            ExternalId(type = "<id_type>", id = "<value>")
        )
    )
)
```
{{% /tab %}}
{{< /tabs >}}

### Method signature {#method-signature-kotlin}

The below table describes the `alias` method signature in detail:

| Field | Data type | Description |
| :----| :------| :-----|
| `newId` | String | New user identifier (`userId`) associated with the user. |
| `previousId` | String | The old user identifier.<br /><br />**Note**: If not provided explicitly, the SDK automatically populates this field with the current `userId` or `anonymousId`. |
| `options` | RudderOption | Additional event options. |

### Example {#example-kotlin}

A sample `alias` event sent from the Android (Kotlin) SDK is shown below:

{{< tabs tabTotal="2" >}}
{{% tab tabName="Kotlin" %}}
```kotlin
analytics.alias(
    newId = "1hKOmRA4GRlm",
    previousId = "156K7m214GR2X",
    options = RudderOption()
)
```
{{% /tab %}}
{{% tab tabName="Java" %}}
```java
analytics.alias("1hKOmRA4GRlm", "156K7m214GR2X", new RudderOption());
```
{{% /tab %}}
{{< /tabs >}}

## iOS (Swift)

The `alias` method definition in the iOS (Swift) SDK is as follows:

{{< tabs tabTotal="2" >}}
{{% tab tabName="Default invocation" %}}
```swift
analytics.alias(
    newId: "<newId>",
    previousId: "<previousId>",
    options: RudderOption()
)
```

{{< warning >}}
Make sure to include the `import RudderStackAnalytics` statement before making the call.
{{< /warning >}}

The corresponding Objective-C snippet is shown below:

```objectivec
[analytics alias:@"<newId>" previousId:@"<previousId>" options:[[RSSOptionBuilder new] build]];
```

{{< info >}}
`RSSOptionBuilder` is an Objective-C–only helper class. It uses the builder pattern to create an `RSSOption` instance and lets you set custom context, configure integrations, and attach external IDs in a structured way.
{{< /info >}}

{{% /tab %}}
{{% tab tabName="Alternate invocations" %}}
```swift
// Alias event with newId
analytics.alias(newId: "Alias ID 1")

// Alias event with newId and previousId
analytics.alias(
    newId: "Alias ID 1",
    previousId: "Explicit Previous User ID 1"
)

// Alias event with newId and options
analytics.alias(
    newId: "Alias ID 1",
    options: RudderOption(
        integrations: [
            "Amplitude": true,
            "INTERCOM": [
                "lookup": "phone"
            ]
        ],
        customContext: [
            "key-1": "value-1"
        ],
        externalIds: [
            ExternalId(type: "brazeExternalId", id: "value1234")
        ]
    )
)
```

The corresponding Objective-C snippet is shown below:

```objectivec
// Alias event with newId
[analytics alias:@"Alias ID 1"];

// Alias event with newId and previousId
[analytics alias:@"Alias ID 1" previousId:@"Explicit Previous User ID 1"];

// Alias event with newId and options
RSSOptionBuilder *optionBuilder = [[RSSOptionBuilder alloc] init];

[optionBuilder setCustomContext:@{
    @"key-1": @"value-1"
}];

[optionBuilder setIntegrations:@{
    @"Amplitude": @YES,
    @"INTERCOM": @{
        @"lookup": @"phone"
    }
}];

[optionBuilder setExternalIds:@[
    [[RSSExternalId alloc] initWithType:@"brazeExternalId" id:@"value1234"]
]];

[analytics alias:@"Alias ID 1" options:[optionBuilder build]];
```
{{% /tab %}}
{{< /tabs >}}

### Method signature {#method-signature-swift}

The below table describes the `alias` method signature in detail:

| Field | Data type | Description |
| :----| :------| :-----|
| `newId` | String | New user identifier (`userId`) associated with the user. |
| `previousId` | String | The old user identifier.<br /><br />**Note**: If not provided explicitly, the SDK automatically populates this field with the current `userId` or `anonymousId`. |
| `options` | RudderOption | Additional event options. |

### Example {#example-swift}

A sample `alias` event sent from the iOS (Swift) SDK is shown below:

{{< tabs tabTotal="2" >}}
{{% tab tabName="Swift" %}}
```swift
analytics.alias(
    newId: "Alias ID 1",
    previousId: "Explicit Previous User ID 1",
    options: RudderOption(
        integrations: [
            "Amplitude": true,
            "INTERCOM": [
                "lookup": "phone"
            ]
        ],
        customContext: [
            "key-1": "value-1"
        ],
        externalIds: [
            ExternalId(type: "brazeExternalId", id: "value1234")
        ]
    )
)
```
{{% /tab %}}
{{% tab tabName="Objective-C" %}}
```objectivec
RSSOptionBuilder *optionBuilder = [[RSSOptionBuilder alloc] init];

[optionBuilder setCustomContext:@{
    @"key-1": @"value-1"
}];

[optionBuilder setIntegrations:@{
    @"Amplitude": @YES,
    @"INTERCOM": @{
        @"lookup": @"phone"
    }
}];

[optionBuilder setExternalIds:@[
    [[RSSExternalId alloc] initWithType:@"brazeExternalId" id:@"value1234"]
]];

[analytics alias:@"Alias ID 1"
         previousId:@"Explicit Previous User ID 1"
            options:[optionBuilder build]];
```
{{% /tab %}}
{{< /tabs >}}