schedule property

List<String>? schedule

Configures an automated, cron-like schedule for the plugin to BackgroundGeolocation.start / BackgroundGeolocation.stop tracking at pre-defined times.

  "{DAY(s)} {START_TIME}-{END_TIME}"

• The START_TIME, END_TIME are in 24h format.
• The DAY param corresponds to the Locale.US, such that Sunday=1; Saturday=7).
• You may configure a single day (eg: 1), a comma-separated list-of-days (eg: 2,4,6) or a range (eg: 2-6)

Example

BackgroundGeolocation.ready(Config(
  .
  .
  .
  schedule: [
    '1 17:30-21:00',    // Sunday: 5:30pm-9:00pm
    '2-6 9:00-17:00',   // Mon-Fri: 9:00am to 5:00pm
    '2,4,6 20:00-00:00',// Mon, Web, Fri: 8pm to midnight (next day)
    '7 10:00-19:00'     // Sat: 10am-7pm
  ]
)).then((State state) {
  // Start the Scheduler
  BackgroundGeolocation.startSchedule();
});

// Listen to #onSchedule events:
BackgroundGeolocation.onSchedule((State state) {
  bool enabled = state.enabled;
  print('[onSchedule] - enabled? ${enabled}');
});
.
.
.
// Later when you want to stop the Scheduler (eg: user logout)
BackgroundGeolocation.stopSchedule();
// You must explicitly stop tracking if currently enabled
BackgroundGeolocation.stop();

// Or modify the schedule with usual #setConfig method
BackgroundGeolocation.setConfig(Config(
  schedule: [
    '1-7 9:00-10:00',
    '1-7 11:00-12:00',
    '1-7 13:00-14:00',
    '1-7 15:00-16:00',
    '1-7 17:00-18:00',
    '2,4,6 19:00-22:00'
  ]
));

Literal Dates

The schedule can also be configured with a literal start date of the form:

  "yyyy-mm-dd HH:mm-HH:mm"

eg:

BackgroundGeolocation.ready(Config(
  schedule: [
    "2018-01-01 09:00-17:00"
  ]
));

Or two literal dates to specify both a start and stop date (note the format here is a bit ugly):

  "yyyy-mm-dd-HH:mm yyyy-mm-dd-HH:mm"

schedule: [
    "2018-01-01-09:00 2019-01-01-17:00"  // <-- track for 1 year
  ]

Scheduling Geofences-only or Location + Geofences Tracking

You can choose to schedule either geofences-only (ie: BackgroundGeolocation.startGeofences or location + geofences (ie: BackgroundGeolocation.start) tracking with each configured schedule by appending the text geofence or location (default):

In the following schedule, the SDK will engage location + geofences tracking between 9am to 5pm. From 6pm to midnight, only geofences will be monitored.

schedule: [
  "1-7 09:00-17:00 location",
  "1-7 18:00-12:00 geofence"
]

Since location is the default tracking-mode, it can be omitted:

schedule: [
  "1-7 09:00-10:00",  // <-- location is default
  "1-7 10:00-11:00 geofence"
  "1-7 12:00-13:00",
  "1-7 13:00-14:00 geofence"

iOS

iOS cannot evaluate the Schedule at the exact time you configure -- it can only evaluate the schedule periodically, whenever your app comes alive.

When the app is running in a scheduled off period, iOS will continue to monitor the low-power, significant location changes API (SLC) in order to ensure periodic schedule evaluation. SLC is required in order guarantee periodic schedule-evaluation when you're configured stopOnTerminate:false, since the iOS Background Fetch API is halted if user manually terminates the app. SLC will awaken your app whenever a "significant location change" occurs, typically every 1000 meters. If the schedule is currently in an off period, this location will not be persisted nor will it be sent to the BackgroundGeolocation.onLocation event -- only the schedule will be evaluated.

When a schedule is provided on iOS, it will be evaluated in the following cases:

• Application pause / resume events.
• Whenever a location is recorded (including SLC)
• Background fetch event

Android

The Android Scheduler uses AlarmManager and typically operates on-the-minute.

Implementation

List<String>? schedule;