BackgroundURLSession#

BackgroundURLSession provides APIs in the Scripting app for creating, resuming, and managing background download and upload tasks that continue running even when your script or app is not active.

Availability: Only available when your script is running in the main app (Script.env === "index").

Namespace: BackgroundURLSession#

1) startDownload(options): URLSessionDownloadTask#

Description: Starts a new background download task.

Signature

1function startDownload(options: {
2  url: string
3  destination: string
4  headers?: Record<string, string>
5  notifyOnFinished?: {
6    success: string
7    failure: string
8  }
9}): URLSessionDownloadTask

Parameters

• url (string): The URL of the file to download.
• destination (string): The local file path where the downloaded file will be saved.
• headers (Record<string, string>, optional): Custom HTTP headers.
• notifyOnFinished ({ success: string, failure: string }, optional): Whether to show a local notification when the download finishes.

Returns

• URLSessionDownloadTask: A download task object (the task starts automatically).

Example

1const task = BackgroundURLSession.startDownload({
2  url: 'https://example.com/file.zip',
3  destination: '/var/mobile/Containers/.../Downloads/file.zip',
4  headers: { 'User-Agent': 'Scripting/1.0' },
5  notifyOnFinished: {
6    success: 'Download completed',
7    failure: 'Download failed'
8  }
9})
10
11task.resum()
12
13task.onProgress = d => console.log('Progress:', d.progress)
14task.onFinishDownload = (err, info) => {
15  if (!err) console.log('Download completed at:', info.destination)
16}

2) resumeDownload(options): URLSessionDownloadTask#

Description: Resumes a previously paused or interrupted download task using resume data.

Signature

1function resumeDownload(options: {
2  resumeData: Data
3  destination: string
4  notifyOnFinished?: {
5    success: string
6    failure: string
7  }
8}): URLSessionDownloadTask

Parameters

• resumeData (Data): The resume data returned by cancelByProducingResumeData().
• destination (string): The path to save the resumed download.
• notifyOnFinished ({ success: string, failure: string }, optional): Whether to show a local notification when the download finishes.

Returns

• URLSessionDownloadTask: A resumed download task (starts automatically).

Example

1const task = BackgroundURLSession.resumeDownload({
2  resumeData,
3  destination: '/.../Downloads/file.zip',
4  notifyOnFinished: {
5    success: 'Resumed download completed',
6    failure: 'Resumed download failed'
7  }
8})
9
10task.resume()
11
12task.onFinishDownload = (err, info) => {
13  if (!err) console.log('Resumed download completed:', info.destination)
14}

3) getDownloadTasks(): Promise<URLSessionDownloadTask[]>#

Description: Retrieves all active or pending background download tasks currently managed by the system. Useful when your script is restarted or relaunched — you can restore callbacks and monitor ongoing tasks.

Signature

1function getDownloadTasks(): Promise<URLSessionDownloadTask[]>

Returns

• Promise<URLSessionDownloadTask[]>: An array of active URLSessionDownloadTask objects.

Example

1const tasks = await BackgroundURLSession.getDownloadTasks()
2for (const task of tasks) {
3  console.log('Task ID:', task.id, 'State:', task.state)
4  task.onComplete = err => {
5    if (err) console.error('Download failed:', err)
6  }
7}

4) startUpload(options): URLSessionUploadTask#

Description: Starts a new background upload task.

Signature

1function startUpload(options: {
2  filePath: string
3  toURL: string
4  method?: string
5  headers?: Record<string, string>
6  notifyOnFinished?: {
7    success: string
8    failure: string
9  }
10}): URLSessionUploadTask

Parameters

• filePath (string): The local file path to upload.
• toURL (string): The destination server URL.
• method (string, optional, default "POST"): The HTTP method to use.
• headers (Record<string, string>, optional): Custom HTTP headers.
• notifyOnFinished ({ success: string, failure: string }, optional): Whether to show a local notification when the upload finishes.

Returns

• URLSessionUploadTask: An upload task object (the task starts automatically).

Example

1const task = BackgroundURLSession.startUpload({
2  filePath: '/.../upload.bin',
3  toURL: 'https://api.example.com/upload',
4  method: 'PUT',
5  headers: { Authorization: 'Bearer token' },
6  notifyOnFinished: {
7    success: 'Upload completed',
8    failure: 'Upload failed'
9  }
10})
11
12task.resume()
13
14task.onComplete = err => {
15  if (!err) console.log('Upload completed')
16  else console.error('Upload failed:', err)
17}

5) resumeUpload(options): URLSessionUploadTask#

Description: Resumes a paused or failed upload task using previously saved resume data (if supported by the server).

Signature

1function resumeUpload(options: {
2  resumeData: Data
3  notifyOnFinished?: {
4    success: string
5    failure: string
6  }
7}): URLSessionUploadTask

Parameters

• resumeData (Data): Resume data returned from a previous incomplete upload.
• notifyOnFinished ({ success: string, failure: string }, optional): Whether to show a local notification when the upload finishes.

Returns

• URLSessionUploadTask: A new resumed upload task (starts automatically).

Example

1const task = BackgroundURLSession.resumeUpload({
2  resumeData,
3  notifyOnFinished: {
4    success: 'Resumed upload completed',
5    failure: 'Resumed upload failed'
6  }
7})
8
9task.resume()
10
11task.onComplete = err => {
12  if (!err) console.log('Resumed upload completed successfully')
13}

6) getUploadTasks(): Promise<URLSessionUploadTask[]>#

Description: Retrieves all active or pending background upload tasks currently managed by the system. Use this method after restarting your script to reattach callbacks to ongoing uploads.

Signature

1function getUploadTasks(): Promise<URLSessionUploadTask[]>

Returns

• Promise<URLSessionUploadTask[]>: An array of active URLSessionUploadTask objects.

Example

1const tasks = await BackgroundURLSession.getUploadTasks()
2for (const task of tasks) {
3  console.log('Task ID:', task.id, 'State:', task.state)
4  task.onComplete = err => {
5    if (err) console.error('Upload failed:', err)
6  }
7}

Usage Notes and Best Practices#

• Start tasks: Tasks begin in a suspended state, so you need to call resume() manually.
• Pause and resume: You can temporarily pause a task using task.suspend() and later call task.resume() to continue.
• Resume support: Download tasks can generate resume data via cancelByProducingResumeData(). Upload resumability depends on server capabilities.
• Task restoration: Even if your script is terminated, ongoing background tasks continue running. When restarted, use getDownloadTasks() or getUploadTasks() to retrieve them and reattach event handlers.
• Local notifications: The notifyOnFinished option only controls whether a notification is shown when a task completes; it does not affect task lifecycle or callbacks.