EventTimelineApi

Use this API to query for historic timeline events, and subscribe for real time timeline updates.

EventTimeline API

getTimelineEvent()

Returns the timeline event with the specified ID, or null if no such event exists.

Note: calling this method on an uninitialized SDK will throw an SdkException.

@Nullable Event getTimelineEvent(String eventId);

Parameters
eventId	The event ID.

getTimelineEvents()

Returns timeline events, such as transport and stationary events, that were captured during the specified date range. The events are ordered from oldest to newest, and are not provisional (see isProvisional).

Events that were captured outside of the specified date range are not returned, even if they were updated during this date range. To get all updates, regardless of when an event was captured, use getTimelineUpdates(Date) instead.

Note: calling this method on an uninitialized SDK will throw an SdkException.

List<Event> getTimelineEvents(Date fromDate, Date toDate);

Parameters
fromDate	The start date of the date range. The specified date is inclusive.
toDate	The end date of the date range. The specified date is inclusive.

getTimelineEventsIncludingProvisionalOnes()

Returns timeline events, such as transport and stationary events, that were captured during the specified date range. The events are ordered from oldest to newest, and may include provisional ones (see isProvisional).

Events that were captured outside of the specified date range are not returned, even if they were updated during this date range. To get all updates, regardless of when an event was captured, use getTimelineUpdates(Date) instead.

Note: calling this method on an uninitialized SDK will throw an SdkException.

List<Event> getTimelineEventsIncludingProvisionalOnes(Date fromDate, Date toDate);

Parameters
fromDate	The start date of the date range. The specified date is inclusive.
toDate	The end date of the date range. The specified date is inclusive.

getTimelineUpdates()

Returns all updated events in the event timeline after the specified date, sorted by the last update time. The received events are not provisional (see isProvisional).

This method returns all events that started after afterDate, but it may also return events that started before afterDate, if they were updated afterwards. The returned result is not necessarily the complete list of events that were captured by the SDK from the result's first event until the last, because events that were not updated will be excluded. To get a complete and ordered list of events for a given date range, use getTimelineEvents(Date, Date) instead.

You can use this method along with setTimelineUpdateListener(EventTimelineUpdateListener) to stay up to date with the latest events in the timeline. For example, to make sure you don't miss out on timeline updates, you can first set an update listener, then follow up by using this method to query for potential updates since the last update you received. Sample code demonstrating this case be found here.

Note: calling this method on an uninitialized SDK will throw an SdkException.

List<Event> getTimelineUpdates(Date afterDate);

Parameters
afterDate	The date to retrieve updates from. The specified date is exclusive.

getTimelineUpdatesIncludingProvisionalEvents()

Returns all updated events in the event timeline after the specified date, sorted by the last update time. The received events may include provisional ones (see isProvisional).

This method returns all events that started after afterDate, but it may also return events that started before afterDate, if they were updated afterwards. The returned result is not necessarily the complete list of events that were captured by the SDK from the result's first event until the last, because events that were not updated will be excluded. To get a complete and ordered list of events for a given date range, use getTimelineEvents(Date, Date) instead.

You can use this method along with setTimelineUpdateListener(EventTimelineUpdateListener) to stay up to date with the latest events in the timeline. For example, to make sure you don't miss out on timeline updates, you can first set an update listener, then follow up by using this method to query for potential updates since the last update you received. Sample code demonstrating this case be found here.

Note: calling this method on an uninitialized SDK will throw an SdkException.

List<Event> getTimelineUpdatesIncludingProvisionalEvents(Date afterDate);

Parameters
afterDate	The date to retrieve updates from. The specified date is exclusive.

setTimelineUpdateListener()

Sets a listener that is invoked when the event timeline is updated. The listener receives the updated events. An update can be triggered by the start of a new event, and the update or end of an existing one. Every invocation of the listener will deliver an event that has a lastUpdateTime that is equal to or greater than the previously delivered event's lastUpdateTime.

The received updates are not provisional. See isProvisional to learn more about what a provisional event is.

You can use this method along with getTimelineUpdates(Date) to stay up to date with the latest events in the timeline. For example, to make sure you don't miss out on timeline updates, you can first set an update listener using this method, then follow up by calling getTimelineUpdates(Date) to query for potential updates since the last update you received. Sample code demonstrating this case be found here.

Note: calling this method on an uninitialized SDK will throw an SdkException.

void setTimelineUpdateListener(@Nullable EventTimelineUpdateListener listener)

Parameters
listener	The listener that will be invoked to deliver the updated timeline event. Pass null to remove the previously set listener. See EventTimelineUpdateListener.

setProvisionalAwareTimelineUpdateListener()

Sets a listener that is invoked when the event timeline is updated. The listener receives the updated events. An update can be triggered by the start of a new event, and the update or end of an existing one. Every invocation of the listener will deliver an event that has a lastUpdateTime that is equal to or greater than the previously delivered event's lastUpdateTime.

The received updates may include provisional events. See isProvisional to learn more about what a provisional event is.

You can use this method along with getTimelineUpdates(Date) to stay up to date with the latest events in the timeline. For example, to make sure you don't miss out on timeline updates, you can first set an update listener using this method, then follow up by calling getTimelineUpdates(Date) to query for potential updates since the last update you received. Sample code demonstrating this case be found here.

Note: calling this method on an uninitialized SDK will throw an SdkException.

void setProvisionalAwareTimelineUpdateListener(@Nullable EventTimelineUpdateListener listener)

Parameters
listener	The listener that will be invoked to deliver the updated timeline event. Pass null to remove the previously set listener. See EventTimelineUpdateListener.

setTransportTags()

Sets the tags that will be assigned to a detected transport.

The provided tags will be assigned to a transport at the moment the transport ends. When you receive a TransportEvent representing the ended transport, it will include these tags.

The supplied tags are persisted and assigned to future transports, even after the app is restarted. By calling this method again, you will replace the tags that will be assigned to future transports.

You can include up to 6 tags (key-value pairs), and each tag component (key or value) must be at most 256 characters. Do not include sensitive personal data in the tags.

This method throws:

• SdkException if invoked while the SDK is not initialized

• NoSentianceUserException if there's no Sentiance user while trying to set the transport tags.

• IllegalArgumentException if the supplied set of tags do not adhere to the maximum allowed tag count, or if a key/value component has more than the maximum allowed characters.

void setTransportTags(Map<String, String> tags);

Parameters
tags	The transport tags to set.