Unexpected optOut behavior for persisted cookie vs. initialization options

[mikeryancodes]

Expected Behavior

• When a user has an Amplitude cookie with optOut: true and we initialize an Amplitude client with optOut: false as an option such that a new session is created, the client is initialized with optOut: false
• Alternatively, an Amplitude client initialized with a new session always has its optOut determined by the same precedence rule of persisted cookie setting vs option, regardless of whether the cookie has optOut: true and the initialization option has optOut: false or the cookie has optOut: false and the initialization option has optOut: true
• Alternatively, there is better documentation around this behavior

Current Behavior

We were using options to determine users' optOut settings. We made a change causing previously opted out users to be opted in. The optOut setting from the users' Amplitude cookies was true, and even though enough time had passed that Amplitude initialized with a new session, the persisted, old cookie value overrode the initialization option and the Amplitude client was initialized opted out.

Possible Solution

The fix depends on whether this is intended behavior, I've made some suggestions above. Also, we may want the initialization option to take precedence regardless of whether initialization starts a new session.

Steps to Reproduce

To confirm that the optOut setting in the cookie is unexpectedly (to me) persisted when true:

1. Ensure that the amp_xxxxxx cookie is deleted
2. Set code up to initialize the Amplitude client with { optOut: true, sessionTimeout: 60 * 1000 } (along with any other non-conflicting params needed for your environment). You can use a callback passed to init that takes instance as an argument and checks instance.isNewSession() and logs accordingly to confirm that a new session was started.
3. Go through a UI flow that will cause the Amplitude client to be initialized
4. Fire an Amplitude event with the initialized client
5. Inspect the amp_xxxxxx cookie and confirm that it has a '1' at index 2 when split on '.' reflecting that the optOut setting was persisted (and is truthy)
6. Confirm that the Amplitude event did not cause an Amplitude API call
7. Wait at least one minute so the session timeout expires and Amplitude will initialize with a new session
8. Change the code setting to optOut: false instead of optOut: true
9. Repeat steps 3 and 4 above
10. Inspect the amp_xxxxxx cookie and confirm that it still is set to optOut
11. Confirm that the Amplitude event did not cause an Amplitude API call

To confirm that the optOut setting in the cookie is not persisted when false:

1. Ensure that the amp_xxxxxx cookie is deleted
2. Set up code to initialize the Amplitude client with { optOut: false, sessionTimeout: 60 * 1000 } (along with any other non-conflicting params needed for your environment). You can use a callback passed to init that takes instance as an argument and checks instance.isNewSession() and logs accordingly to confirm that a new session was started.
3. Go through a UI flow that will cause the Amplitude client to be initialized
4. Fire an Amplitude event with the initialized client
5. Inspect the amp_xxxxxx cookie and confirm that it has '' at index 2 when split on '.', reflecting that the optOut setting was persisted (and is falsy)
6. Confirm that the Amplitude event caused an Amplitude API call
7. Wait at least one minute so the session timeout expires and Amplitude will initialize with a new session
8. Change the code setting to optOut: true instead of optOut: false
9. Repeat steps 3 and 4 from this section
10. Inspect the amp_xxxxxx cookie and confirm that it now indicates optOut: true
11. Confirm that the Amplitude event did not cause an Amplitude API call

Other

See this commit. The wording of the test that was added ('should favor the config optOut setting over cookie optOut if the config optOut is set to true') makes me think this could be intended behavior.

Using an init callback and calling instance.setOptOut(optOut) gives the client the correct optOut setting.

Environment

• JS SDK Version: amplitude-js version 8.17.0
• Installation Method: npm
• Browser and Version: Chrome Version 102.0.5005.61 (Official Build) (x86_64)