Fix the alias api in the libraries to match the docs

[lharries]

The backend library types and the docs have diverged. I've gone through the different libraries and updated the errors I've seen

Currently the docs state that the API is as follows: posthog.alias('distinct_id', 'alias_id); where alias_id is added as an alias of the user with distinct_id. The properties of user with distinct_id take president

Library fixes:

1. iOS. Docs are the wrong way around, fix here: Update alias doc strings posthog-ios#34
2. Python. Fix for library and docs Update alias docs posthog-python#82

The other libraries are fine or it's not implemented

I've also noted an error in our own code where it looks like we are using it wrong:
PostHog/posthog#13906

• @lharries confirm that aliasing works as expected

[lharries]

Aliasing doesn't seem to work currently as I'd expect

import posthog

posthog.project_api_key = "KEY"

distinct_id = "distinct_id"

alias_id = "alias_id"

posthog.capture(distinct_id, "distinct id test event")

posthog.capture(alias_id, "alias test event 1")

posthog.alias(distinct_id, alias_id)

posthog.capture(
    alias_id, "alias test event 2"
)  # this should be associated with distinct_id, however it's not

[lharries]

I'm seeing some unexpected behaviour:

1. Using the script above, doesn't seem to result in the users being alias. alias_id is still a distinct person and none of the future events are associated with distinct_id
2. If (with fresh IDs) I remove the alias_id capture event and then try again, it does merge them however it identifies the user as the alias_id ID primarily in the UI when from our docs I'd expect this to primarily be distinct_id e.g. https://app.posthog.com/person/new_distinct_id

Bonus

1. (Not a bug we should likely do something here at one point) You can't tell in the events table when a person is actually an alias e.g. these are all the same person:

[tiina303]

(Not a bug we should likely do something here at one point) You can't tell in the events table when a person is actually an alias e.g. these are all the same person:

typically people set Person Display Name in their project settings in which case they would look the same (even if they aren't). Would be nice I agree if it would be easy to know if the same person or not.

Aliasing doesn't seem to work currently as I'd expect

The reason why your test didn't work is because you used an illegal distinct_id (see https://posthog.com/docs/integrate/identifying-users#considerations), with witch we don't allow merges, if you head over to https://app.posthog.com/data-management/ingestion-warnings
you'll see

Refused to merge an illegal distinct_id [distinct_id](https://app.posthog.com/person/distinct_id) with [alias_id](https://app.posthog.com/person/alias_id) via an $identify or $create_alias call

If you change your ids to be valid ones, then it works as expected.

[tiina303]

btw I see that we have added this into https://posthog.com/docs/integrate/identifying-users (it's not clear to me which way I should provide the IDs from this example, but it's important)

If you use a different identifier or multiple identifiers, be sure to alias the two IDs together for example on the backend with posthog-node

JavaScript

posthog.alias({
distinctId: user.id,
alias: user.alternativeId,
})

[tiina303]

I've proposed us to explain things this way: https://posthog.com/docs/integrate/server/node#alias

An alias call requires:

distinctId – the user id
alias – the anonymous session distinct ID
For example:

Node.js

client.alias({
distinctId: 'user:123',
alias: 'session:12345',
})

[neilkakkar]

Curious: Is there a reason why aliasing isn't commutative? (i.e. merging A into B, is not same as merging B into A)?

One reason I can think of is that we discard properties of the aliased id. If this is true, can we explain what aliasing does using this lens? Since, if it were commutative, it wouldn't matter which id came first, but if it does matter, what exactly changes for the second ID?

Otherwise, trying to remember the ordering here is very confusing, and we don't (yet) do a good job of giving users a good conceptual model to make this easier.