Background Jobs

registerBackgroundFetch can be used to register a background fetch job. A JavaScript function that can be invoked whenever the system schedules the fetch task. The app is woken up after the specified amount of fetchInterval.

NOTE: At the end of the background fetch job, you must invoke the kony.backgroundjob.setBackgroundFetchCompletionStatus passing a result that indicates whether content is available or not.

Syntax

kony.backgroundjob.registerBackgroundFetch (backgroundCallBack, fetchInterval);

Input Parameters

backgroundCallBack [Function] - Mandatory

This callback is to be executed when the system invokes the app for a fetch job when the app is in background.

fetchInterval [Number] / [Constant] - Optional

Indicates the minimum time interval in seconds which must elapse before system can invoke the app for next fetch job .This is an optional parameter and value that is specified is only indicative and might not have any real effects on the scheduling frequency, as system decides the actual interval.

Possible values are:

• constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM: This is the default value. System decides the fetch interval depending on the usage prediction for the app.
• constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER: Disable background task. Set the time interval to constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER so that the job is no longer scheduled for running.
• Time in seconds. (Negative values are not accepted).

Return Values

None

Exceptions and Error Handling

• If no arguments or less number of arguments than the mandatory number of arguments are provided, it raises an exception and throws a “KonyError” JS Object with the following attributes:

errorCode: 4001.

name: "BackgroundJobError".

message: "registerBackgroundFetch: MissingMandatoryParameters."

• If arguments type does not match the allowed type, it raises an exception and throws a KonyError JavaScript Object with the following attributes:

errorCode: 4002.

name: "BackgroundJobError".

message: "registerBackgroundFetch: InvalidParameters."

Example

function backgroundFetchCallBack() {

//fetch handler invoked whenever the system invokes the App for a fetch job 
// do something here


// in the end of the handler setBackgroundFetchCompletionStatus() need
// to be called mandatorily other wise system might termitane the app. 

// task completion status. 
//1. constants.BACKGROUND_TASK_STATUS_NEW_DATA
//2. constants.BACKGROUND_TASK_STATUS_FAILED
//3. constants.BACKGROUND_TASK_STATUS_NO_NEW_DATA

var completionStatus = constants.BACKGROUND_TASK_STATUS_NEW_DATA;
        kony.backgroundjob.setBackgroundFetchCompletionStatus(completionStatus);

};


	//Fetch interval
	//1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM
    //2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER
    //3. Time in seconds. (Negative values are not accepted).

    var fetchInterval = constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM;

	//register background fetch job
    kony.backgroundjob.registerBackgroundFetch(backgroundFecthCallBack, fetchInterval);

Platform Availability

Available in iOS Platform.

One must call this method in the end of backgroundCallBack passing a result that indicates whether content was available or not. This method intimates the system of the completion status of the background fetch job that has been scheduled.

Executing this call tells the system that it can move the app back to the suspended state and evaluate its power usage. Apps that download small amounts of content quickly and accurately display when they have content to download are more likely to receive execution time in the future than apps that take longer to download their content

Failure to call this method results in undefined behavior and could cause the app to be terminated by the system. If an error arises during invoking this API, default value: constants.BACKGROUND_TASK_STATUS_FAILED will be set.

Signature

JavaScript: kony.backgroundjob.setBackgroundFetchCompletionStatus(completionStatus)

Input Parameters

completionStatus [constant] - Mandatory

This is a mandatory parameter. Possible values are as follows

• constants.BACKGROUND_TASK_STATUS_NEW_DATA: This tells the system that the fetch was successful and internally, the system then updates the apps UI (if the fetch resulted in UI change) in the background. This new UI is presented to the user once the app is brought to fore ground. The snapshot of the new UI is also presented when the user tries to switch apps using the App switcher.
• constants.BACKGROUND_TASK_STATUS_FAILED: This tells the system that the fetch was unsuccessful. UI is not updated and the task will be run later based on the available system resources.
• constants.BACKGROUND_TASK_STATUS_NO_NEW_DATA: This intimates the system the fetch did not result in any new data, UI is not updated and the job is run after any point later in time but not before the fetch Interval.

Return Values

None

Exceptions

• If no arguments or less number of arguments than the mandatory number of arguments are provided, it raises an exception and throws a “KonyError” JS Object with the following attributes:

errorCode: 4001. 

name: "BackgroundJobError". 

message: "setBackgroundFetchCompletionStatus: MissingMandatoryParameters."

• If arguments type does not match the allowed type, it raises an exception and throws a “KonyError” JS Object with the following attributes:

errorCode: 4002. 

name: "BackgroundJobError". 

message: "setBackgroundFetchCompletionStatus: InvalidParameters."

• If an error arises during invoking of this API, default value: constants.BACKGROUND_TASK_STATUS_FAILED will be set.

Example

function backgroundFecthCallBack() {

//fetch handler invoked whenever the system invokes the App for a fetch job 
// do something here


// in the end of the handler setBackgroundFetchCompletionStatus() need
// to be called mandatorily other wise system might termitane the app. 

// task completion status. 
//1. constants.BACKGROUND_TASK_STATUS_NEW_DATA
//2. constants.BACKGROUND_TASK_STATUS_FAILED
//3. constants.BACKGROUND_TASK_STATUS_NO_NEW_DATA

var completionStatus = constants.BACKGROUND_TASK_STATUS_NEW_DATA;
        kony.backgroundjob.setBackgroundFetchCompletionStatus(completionStatus);

};


	//Fetch interval
	//1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM
    //2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER
    //3. Time in seconds. (Negative values are not accepted).

    var fetchInterval = constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM;

	//register background fetch job
    kony.backgroundjob.registerBackgroundFetch(backgroundFecthCallBack, fetchInterval);

Platform Availability

Available in iOS Platform.

This method sets the fetch interval for the background fetch job scheduled.

Syntax

kony.backgroundjob.setBackgroundFetchInterval(fetchInterval);

Input Parameters

fetchInterval [Number]/[Constant] - Mandatory

Indicative minimum time interval in seconds that should elapse before system can invoke the app for next fetch job. This is only indicative and may not have any real effects on the scheduling frequency, as system decides the actual interval.

Possible values are:

• constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM : This is the default value. System decides the fetch interval depending on the usage prediction for the app.
• constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER: Disable background task. Set the time interval to constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER so that the job is no longer scheduled for running.
• Time in seconds. (Negative values are not accepted).

Return Values

None

Exceptions

• If no arguments or less number of arguments than the mandatory number of arguments are provided, it raises an exception and throws a “KonyError” JS Object with the following attributes:

errorCode: 4001. 

name: "BackgroundJobError". 

message: "setBackgroundFetchInterval: MissingMandatoryParameters."

• If arguments type does not match the allowed type, it raises an exception and throws a “KonyError” JS Object with the following attributes:

errorCode: 4002. 

name: "BackgroundJobError". 

message: "setBackgroundFetchInterval: InvalidParameters."

Example

//Fetch interval 
	//1. constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM
    //2. constants.BACKGROUND_TASK_FETCH_INTERVAL_NEVER
    //3. Time in seconds. (Negative values are not accepted).

    var fetchInterval = constants.BACKGROUND_TASK_FETCH_INTERVAL_MINIMUM;
	
	kony.backgroundjob.setBackgroundFetchInterval(fetchInterval);

Platform Availability

Available in iOS Platform.