HeadlessEvent¶

The event object delivered to a headless task handler when the app is running in a terminated (headless) state on Android.

Warning

You must be prepared to write Java code.

Step 1: Create a file named BackgroundFetchHeadlessTask.java in your app (e.g. src/android/). The file can be located anywhere but MUST be named BackgroundFetchHeadlessTask.java:

package com.transistorsoft.cordova.backgroundfetch;

import android.content.Context;
import android.util.Log;

import com.transistorsoft.tsbackgroundfetch.BackgroundFetch;
import com.transistorsoft.tsbackgroundfetch.BGTask;

public class BackgroundFetchHeadlessTask implements HeadlessTask {
    @Override
    public void onFetch(Context context, BGTask task) {
        String taskId = task.getTaskId();
        boolean isTimeout = task.getTimedOut();
        if (isTimeout) {
            Log.d(BackgroundFetch.TAG, "TIMEOUT: " + taskId);
            BackgroundFetch.getInstance(context).finish(taskId);
            return;
        }
        Log.d(BackgroundFetch.TAG, "onFetch: " + taskId);
        // Perform your work here...

        BackgroundFetch.getInstance(context).finish(taskId);
    }
}

Step 2: In your config.xml, add a <resource-file> within <platform name="android">:

<platform name="android">
    <resource-file
        src="src/android/BackgroundFetchHeadlessTask.java"
        target="app/src/main/java/com/transistorsoft/cordova/backgroundfetch/BackgroundFetchHeadlessTask.java" />
</platform>

src: path to your custom BackgroundFetchHeadlessTask.java.
target: must be exactly as shown above.

taskId¶

taskId: string;

The identifier of the task that fired this headless event.

Pass this value to BackgroundFetch.finish when your work is complete.

timeout¶

timeout: boolean;

true when the OS signals that background running-time is nearly exhausted.

When a timeout event fires you must immediately call BackgroundFetch.finish and stop any in-progress work. Failure to do so may cause the OS to penalize your app.