Contextual History

The Tizen platform collects data on the device usage. Based on this data, the applications can take advantage of the user's application usage patterns through statistical analysis.

This feature is supported in mobile applications only.

The Contextual History API provides history data about application usage, media playback, communications, and device settings. When an application reads each type of history data, the application can set filters to specify the necessary statistics. The following example shows how to get information about the 5 most frequently used applications from the last 30 days.

// Setting filter key and values
context_history_filter_set_int(filter, CONTEXT_HISTORY_FILTER_RESULT_SIZE, 5);
context_history_filter_set_int(filter, CONTEXT_HISTORY_FILTER_TIME_SPAN, 30);

// Requesting the statistics
context_history_list_h list;
context_history_get_list(handle, CONTEXT_HISTORY_FREQUENTLY_USED_APP, filter, &list);

Once the context_history_list_h data handle is retrieved through the context_history_get_list() function, the attributes of each data record of the handle can be retrieved. You can use the context_history_list_get_current() function to get the current record and the context_history_record_get_string() and context_history_record_get_int() functions to access its values.

History Data Types

Through contextual history, you can mainly retrieve statistics for 3 categories of usage logs, including application usage, media playback, and communications. The following table summarizes the available history data types and required privileges.

Table: History data types and required privileges
History type	Description and privilege
Application usage history: CONTEXT_HISTORY_RECENTLY_USED_APP CONTEXT_HISTORY_FREQUENTLY_USED_APP CONTEXT_HISTORY_RARELY_USED_APP CONTEXT_HISTORY_PEAK_TIME_FOR_APP CONTEXT_HISTORY_COMMON_SETTING_FOR_APP	The contextual history contains data on which applications are used in the foreground. From this data, the following statistics are provided: Most recently or frequently used applications, in a descending order of the application use counts. Most rarely used applications in removable applications, in an ascending order of the application use counts. Peak time for applications, or the time period when the user most frequently uses an application during the day. The result is a sorted list of hours of the day, in a descending order of the application use count in each one-hour time slot. Common settings for applications, or the most common setting values regarding an application or any applications. The required privilege is http://tizen.org/privilege/apphistory.read.
Media playback history: CONTEXT_HISTORY_PEAK_TIME_FOR_MUSIC CONTEXT_HISTORY_PEAK_TIME_FOR_VIDEO CONTEXT_HISTORY_COMMON_SETTING_FOR_MUSIC CONTEXT_HISTORY_COMMON_SETTING_FOR_VIDEO	Media playback events, including music and video playback, can be logged. From this data, the following statistics are provided: Peak time for music or video playback, or the time period when the user most frequently listens to music or watches videos during the day. The result is a sorted list of hours of the day, in a descending order of the playback count in each one-hour time slot. Common settings for music or video playback, or the most common setting values when listening to music or watching videos. The required privilege is http://tizen.org/privilege/mediahistory.read. For more information on other media content metadata, such as when or how many times media content is played, see the Media Content guide.
Communication history: CONTEXT_HISTORY_FREQUENTLY_COMMUNICATED_ADDRESS	Applications can retrieve the contacts the user has called or messaged most frequently. The required privilege is http://tizen.org/privilege/callhistory.read. For more detailed information on the communication history, see the Contacts guide.

Note
To compute the above usage history statistics, it is necessary to store and aggregate contextual events. In many cases, immediately reflecting the contextual events to the statistics costs more than applying the events in a batch later. For this reason, the above history statistics may not show up-to-date results all the time.

Filters and Attributes

Regarding each history data type, one or more filters can be set to specify the necessary statistics. For example, applications can get information about the 3 most frequently used applications from the last 30 days while a headphone is connected by setting the filters of the result size, time span, and the audio jack status. The supported filters for the history data types are summarized in the following table.

Table: Supported filters for history data
History type	Supported filter	Type	Description
All types	CONTEXT_HISTORY_FILTER_TIME_SPAN	Integer	This filter specifies in days the time span of the data to be aggregated. For example, if the value is set to 10, the application gets the statistics from the data logged in the last 10 days. Only positive filter values are allowed. Because of the system resources available, the maximum time span can be limited implicitly. If the value is not set, the default value of 30 days is used.
All types	CONTEXT_HISTORY_FILTER_START_TIME CONTEXT_HISTORY_FILTER_END_TIME	Integer	If an application requires more fine-grained controls than the time span filter, the start and end time of the period can be set as Unix epoch time in seconds using these filters. It is also possible to set the start time or the end time only.
All types, except: CONTEXT_HISTORY_COMMON_SETTING_FOR_APP CONTEXT_HISTORY_COMMON_SETTING_FOR_MUSIC CONTEXT_HISTORY_COMMON_SETTING_FOR_VIDEO	CONTEXT_HISTORY_FILTER_RESULT_SIZE	Integer	This filter limits the number of data records to be retrieved. It accepts positive integers as the filter values, but if not set, it is set to 10 by default. It is possible that the aggregated result contains a smaller number of records than the filter value. Note that this value may have no effect for some history types. For example, the common setting history types return one record for one request, thus the result size is ignored while aggregating the logs.
CONTEXT_HISTORY_RECENTLY_USED_APP CONTEXT_HISTORY_FREQUENTLY_USED_APP	CONTEXT_HISTORY_FILTER_WIFI_BSSID	String	Applications can get the statistics of the data logged while a specific Wi-Fi is connected, by setting the BSSID string of the target Wi-Fi AP. The currently connected Wi-Fi AP's BSSID can be retrieved through the Wi-Fi Manager APIs. For more information, see the Wi-Fi guide.
	CONTEXT_HISTORY_FILTER_AUDIO_JACK	Integer	Applications can get the statistics of the data logged while the headphone is connected or disconnected. The audio jack status can be either CONTEXT_HISTORY_FILTER_AUDIO_JACK_NOT_CONNECTED or CONTEXT_HISTORY_FILTER_AUDIO_JACK_CONNECTED.
CONTEXT_HISTORY_PEAK_TIME_FOR_APP CONTEXT_HISTORY_COMMON_SETTING_FOR_APP	CONTEXT_HISTORY_FILTER_APP_ID	String	Use this filter to compute the peak time (or the common settings) for a specific application. Without this filter, the peak time (or the common setting) is computed from the usage history of all applications. For more information on the application IDs, see the Application Framework guide.
CONTEXT_HISTORY_PEAK_TIME_FOR_APP CONTEXT_HISTORY_PEAK_TIME_FOR_MUSIC CONTEXT_HISTORY_PEAK_TIME_FOR_VIDEO	CONTEXT_HISTORY_FILTER_DAY_OF_WEEK	Integer	Use this filter to get usage patterns on weekdays or weekends. The filter value can be either CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_WEEKDAYS, CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_WEEKENDS, or CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_ALL. Without this filter, data from both weekdays and weekends are used.
CONTEXT_HISTORY_FREQUENTLY_COMMUNICATED_ADDRESS	CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE	Integer	By default, communication frequency is computed from the call and message logs. Applications can narrow down the target data to one type of communication, call or messaging, using this filter. The filter value can be either CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE_CALL, CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE_MESSAGE, or CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE_ALL.

The history data records retrieved through the contextual history API contain the following data attributes.

Table: Attributes provided by history data
History type	Provided attribute	Type	Description
CONTEXT_HISTORY_RECENTLY_USED_APP CONTEXT_HISTORY_FREQUENTLY_USED_APP CONTEXT_HISTORY_RARELY_USED_APP	CONTEXT_HISTORY_APP_ID	String	This attribute denotes the application ID. For more information on the application IDs, see the Application Framework guide.
	CONTEXT_HISTORY_TOTAL_COUNT	Integer	This attribute denotes how many times the application is used in the foreground.
	CONTEXT_HISTORY_TOTAL_DURATION	Integer	This attribute denotes the time the application is being displayed in the foreground in seconds. If the application is used multiple times, it denotes the accumulated time of use.
	CONTEXT_HISTORY_LAST_TIME	Integer	This attribute denotes when the application has been used (moved to the foreground) the last time, in Unix epoch in seconds.
CONTEXT_HISTORY_PEAK_TIME_FOR_APP CONTEXT_HISTORY_PEAK_TIME_FOR_MUSIC CONTEXT_HISTORY_PEAK_TIME_FOR_VIDEO	CONTEXT_HISTORY_HOUR_OF_DAY	Integer	This attribute denotes the hour of the day. Its value is an integer from 0 to 23.
	CONTEXT_HISTORY_TOTAL_COUNT	Integer	This attribute denotes the aggregated count of the application uses or media playbacks within the hour of the day defined with CONTEXT_HISTORY_HOUR_OF_DAY.
CONTEXT_HISTORY_COMMON_SETTING_FOR_APP CONTEXT_HISTORY_COMMON_SETTING_FOR_MUSIC CONTEXT_HISTORY_COMMON_SETTING_FOR_VIDEO	CONTEXT_HISTORY_AUDIO_JACK	Integer	This attribute denotes the most common audio jack status. The value is either CONTEXT_HISTORY_FILTER_AUDIO_JACK_NOT_CONNECTED or CONTEXT_HISTORY_FILTER_AUDIO_JACK_CONNECTED.
	CONTEXT_HISTORY_SYSTEM_VOLUME	Integer	This attribute denotes the most common system volume level.
	CONTEXT_HISTORY_MEDIA_VOLUME	Integer	This attribute denotes the most common media volume level. For more information on the system and media volume settings, see the Sound Manager guide.
CONTEXT_HISTORY_FREQUENTLY_COMMUNICATED_ADDRESS	CONTEXT_HISTORY_ADDRESS	String	This attribute denotes the contact address or a phone number.
	CONTEXT_HISTORY_TOTAL_COUNT	Integer	This attribute denotes the total number of communications with the address defined with CONTEXT_HISTORY_ADDRESS.
	CONTEXT_HISTORY_TOTAL_DURATION	Integer	This attribute denotes the accumulated duration of calls in seconds with the address defined with CONTEXT_HISTORY_ADDRESS.
	CONTEXT_HISTORY_LAST_TIME	Integer	This attribute denotes when a call is connected or a message is received or sent last in Unix epoch in seconds, to or from the address defined with CONTEXT_HISTORY_ADDRESS.