fix: add setSessionId() method

[falconandy]

Summary

Adds setSessionId() method.

Typical usage is amplitude.setSessionId(timestamp: Int64(NSDate().timeIntervalSince1970 * 1000))

Maybe it makes sense to add:

• method startNewSession() (without any parameters, the same as setSessionId(timestamp: Int64(NSDate().timeIntervalSince1970 * 1000)))
• method endCurrentSession() to end the current session but do not start new session. Can be used in client Log Out logic. Maybe it can be used inside SDK reset() method.

Checklist

• Does your PR title have the correct title format?
• Does your PR have a breaking change?: No

[justin-fiedler]

Typical usage is amplitude.setSessionId(timestamp: Int64(NSDate().timeIntervalSince1970 * 1000))

Maybe it makes sense to add:

• method startNewSession() (without any parameters, the same as setSessionId(timestamp: Int64(NSDate().timeIntervalSince1970 * 1000)))
• method endCurrentSession() to end the current session but do not start new session. Can be used in client Log Out logic. Maybe it can be used inside SDK reset() method.

Thanks @falconandy. I agree the current usage is pretty clunky.

A couple options:

1. New methods like you suggest. I would prefer naming them sessionStart(timestamp? = Date.now()) and sessionEnd() to keep them grouped in IDE autocomplete. wdyt?
2. New convenience method setSessionId(date: Date)) with usage amplitude.setSessionId(date: Date())

I like that #2 as it's a smaller footprint, but I think #1 is easier to understand.

I am leaning towards #1, or both. Wdyt?

[falconandy]

@justin-fiedler
I added all 3 methods.

Parameter naming (wdyt?):
For setSessionId() the parameter is timestamp: Int64
For sessionStart() the parameter is optional at: Date = Date()
For sessionEnd() the parameter is optional at: Date? = nil. nil means last known event time but explicit value can be set to use current time, for example. Also explicit at value is used in tests.

[justin-fiedler]

I added all 3 methods.

Parameter naming (wdyt?): For setSessionId() the parameter is timestamp: Int64 For sessionStart() the parameter is optional at: Date = Date() For sessionEnd() the parameter is optional at: Date? = nil. nil means last known event time but explicit value can be set to use current time, for example. Also explicit at value is used in tests.

Thanks @falconandy!

I thought about this more and discussed with the team. We feel that option 2 is the way to go for these reasons

1. Setting the session id is viewed as "advanced" usage. In general sessions are automatically handled by the SDK and we don't want customers to feel they need to do this themselves. By adding sessionStart() and sessionEnd() it makes this functionality more visible to customers and they then may try to manange sessions themselves which could cause more harm than good.
2. Less methods to support/document
3. Keeps the same interface for all SDKs

TLDR; Can you please

1. Remove sessionStart() and sessionEnd()
2. Add setSessionId(date: Date) method. Note no default value for date.
3. Keep setSessionId(timestamp: Int64).

Thank you!

[falconandy]

@justin-fiedler
setSessionId() method always starts new session. Are there any cases when current session should be ended and new session shouldn't be started? For example, on logout event. New session would be started later, on login event.

[justin-fiedler]

setSessionId() method always starts new session. Are there any cases when current session should be ended and new session shouldn't be started? For example, on logout event. New session would be started later, on login event.

Thanks @falconandy for this case I believe customers can use setSessionId(timestamp: -1) and later setSessionId(date: Date())

[falconandy]

@justin-fiedler
ok, sessionStart/sessionEnd are removed, setSessionId(timestamp: - 1) support is added
Next question: how long the explicit session Id (-1 as a special case) should be preserved and how/when return to auto-tracking?

1. Forever.
2. Until app restart.
3. Until app background/foreground
4. Until next event (for session -1).
5. etc

Right now usual session logic works:

• setSession(-1) ends current session, any next event starts new session.
• setSession(timestamp) ends current session, starts new session, session logic works as before (minTimeBetweenSessionMillis can start new session)

[github-actions]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• GitHub release
• v1.0.0

Your semantic-release bot 📦🚀