# BackgroundSync

Background Sync is a feature provided by service workers that enables your Progressive Web App to defer actions until the user has stable connectivity. This is particularly useful for ensuring any requests or data submitted by the user are not lost if their internet connection is unreliable.

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    serviceworker:
        enabled: true
        src: "sw.js"
        workbox:
            background_sync:
                - queue_name: 'api'
                  match_callback: 'startsWith: /api/' # All requests starting with /api/
                  method: POST
                  max_retention_time: 7_200 # 5 days in minutes
                  force_sync_fallback: true #Optional
                  broadcast_channel: 'api-list'
                - queue_name: 'contact'
                  regex: /\/contact-form\// # All requests starting with /contact-form/
                  method: POST
                  max_retention_time: 120 # 2 hours in minutes
```

{% endcode %}

### Configuration Parameters

#### queue\_name

**Type**: `string` **Required**: Yes

Unique queue name to identify and manage separate background sync processes. Essential for categorizing different types of requests such as API calls and form submissions.

```yaml
queue_name: 'form-submissions'
```

#### match\_callback

**Type**: `string` **Required**: Yes

Defines which requests should be queued for background sync. Uses the same match callback system as [resource caching](/1.4.x/the-service-worker/workbox/resource-caching.md#match-callback).

**Supported patterns**:

* `startsWith: /path/` - Match URLs starting with a path
* `regex: /pattern/` - Match URLs with regex pattern
* `origin: https://api.example.com` - Match specific origin
* JavaScript callback - Custom matching logic

**Examples**:

```yaml
match_callback: 'startsWith: /api/'  # All API calls
match_callback: 'regex: /\/submit\//''  # Submission endpoints
match_callback: '({url}) => url.pathname.includes("/api/")'  # Custom
```

See [Resource Caching Match Callback documentation](/1.4.x/the-service-worker/workbox/resource-caching.md#match-callback) for complete details.

#### method

**Type**: `string` **Default**: `POST`

HTTP method for requests to be queued. Typically POST for form submissions and data modifications.

```yaml
method: POST
# or
method: PUT
```

#### max\_retention\_time

**Type**: `integer` (minutes) **Required**: Yes

Maximum time a request will be retried in the background. After this duration, failed requests are discarded.

```yaml
max_retention_time: 7200  # 5 days in minutes
# or
max_retention_time: 120   # 2 hours
```

**Recommendations**:

* **Critical data**: 7200 minutes (5 days)
* **User forms**: 2880 minutes (2 days)
* **Analytics**: 1440 minutes (1 day)
* **Comments/posts**: 720 minutes (12 hours)

#### force\_sync\_fallback

**Type**: `boolean` **Default**: `false` **Optional**: Yes

Forces background sync to attempt a sync even under conditions where it might not normally do so. Useful in critical data submission scenarios.

```yaml
force_sync_fallback: true
```

**When to use**:

* Critical business transactions
* Payment submissions
* User registration data
* Important form submissions

#### broadcast\_channel

**Type**: `string` **Optional**: Yes

Name of the Broadcast Channel API channel for communicating sync status to your application. Enables real-time UI updates about sync progress.

```yaml
broadcast_channel: 'form-sync-status'
```

See the [Sync Broadcast Stimulus Component](https://github.com/Spomky-Labs/phpwa-doc/blob/1.4/symfony-ux/sync-broadcast.md) for implementation details on receiving these updates in your frontend.

#### Additional Parameters

**error\_on\_4xx**: `boolean` (default: `false`)

* Treat 4xx status codes as errors requiring retry

**error\_on\_5xx**: `boolean` (default: `true`)

* Treat 5xx status codes as errors requiring retry

**expect\_redirect**: `boolean` (default: `false`)

* Expect redirect responses as success

**expected\_status\_codes**: `array`

* List of specific status codes to treat as success


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pwa.spomky-labs.com/1.4.x/the-service-worker/workbox/backgoundsync.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.