Contextual Device Usage History Data

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.

The Contextual History API provides history data about application usage, media playback, communications, and device settings. Among context history data types, CONTEXT_HISTORY_RECENTLY_USED_APP, CONTEXT_HISTORY_FREQUENTLY_USED_APP, CONTEXT_HISTORY_BATTERY_USAGE, and CONTEXT_HISTORY_RECENT_BATTERY_USAGE are available for both mobile and wearable devices. The other history data types are supported in mobile applications only.

The main features of the Contextual History API include:

• Getting a profile data list

  You can get the device usage history profiles as a list of data records.

  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);
  

• Enumerating profile data lists

  You can enumerate the records contained in the retrieved profile data list.

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

Prerequisites

To use the functions and data types of the Contextual History API (in mobile and wearable applications), include the <context_history.h> header file in your application:

#include <context_history.h>

Getting a Profile Data List

To retrieve a contextual history profile:

1. Create 2 handles: 1 for using the Contextual History API and 1 for the filter:

   /* Contextual History API handle */
   context_history_h handle;
   context_history_create(&handle);
   
   /* Filter handle */
   context_history_filter_h filter;
   context_history_filter_create(&filter);
   

2. Get information about the 5 applications used most frequently during the last 2 weeks (14 days):

   /* Requesting the top 5 applications */
   context_history_filter_set_int(filter, CONTEXT_HISTORY_FILTER_RESULT_SIZE, 5);
   
   /* Limiting the time span of usage logs to 14 days */
   context_history_filter_set_int(filter, CONTEXT_HISTORY_FILTER_TIME_SPAN, 14);
   

3. Retrieve profile data based on the defined filter:

   context_history_list_h list;
   
   /* Getting the list of records */
   context_history_get_list(handle, CONTEXT_HISTORY_FREQUENTLY_USED_APP, filter, &list);
   
   /* Release the filter after use */
   context_history_filter_destroy(filter);
   

Enumerating Profile Data Lists

The list retrieved using the context_history_get_list() function contains a sorted list of records, each of which consists of a key and value pair.

To enumerate the list:

1. Check the number of records in the list.

   In some cases, the retrieved list can contain less records than the result size set in the filter.

   int size;
   context_history_list_get_count(list, &size);
   

2. Enumerate the list using a loop:

   int i;
   int count;
   char* app_id;
   context_history_record_h record;
   
   for (i = 0; i < size; ++i) {
       /* Getting the current record */
       context_history_list_get_current(list, &record);
   
       /* Retrieving the application ID and the total use count from the record */
       context_history_record_get_string(record, CONTEXT_HISTORY_APP_ID, &app_id);
       context_history_record_get_int(record, CONTEXT_HISTORY_TOTAL_COUNT, &count);
   
       /* Freeing the application ID string */
       free(app_id);
   
       /* Releasing the memory occupied by the record */
       context_history_record_destroy(record);
   
       /* Iterating to the next record */
       context_history_list_move_next(list);
   }
   

3. Release the list to prevent any resource leaks:

   context_history_list_destroy(list);
   

4. When no longer needed, release and destroy the handle:

   context_history_destroy(handle);
   

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

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, 1 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 by setting the filters of the result size and time span. The supported filters for the history data types are summarized in the following table.

Table: Supported filters for history data

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

Table: Attributes provided by history data

Related Information

• Dependencies
  • Tizen 2.4 and Higher for Mobile
  • Tizen 4.0 and Higher for Wearable