Home
Guides
Sign Up

self-hosted-async-mobile-upload

Enabling Async Image Upload in Self-Hosted Mobile Sessions

Overview

After recent improvements to the mobile SDK, image assets are uploaded asynchronously directly to your environment's object storage. Recent LogRocket chart versions enable backend ingest by default so the SDK can request signed upload URLs, and automatically configure replay for the existing fileStorage.buckets.userFiles bucket or container on standard GCP, AWS, and Azure storage setups.

For standard storage setups, no additional Helm values are required. Customers already have fileStorage.buckets.userFiles configured, and the chart derives the replay asset URL from that existing configuration.

Only set cachedAssetPrefixes when replay needs an additional browser-reachable URL prefix that the chart cannot derive, such as a legacy bucket, CDN, proxy, custom S3 endpoint, or another nonstandard public object storage URL.

What Must Be Reachable

When backend ingest is enabled, the mobile SDK requests signed upload URLs for image assets that haven't been uploaded yet. Backend ingest signs those URLs for objects in fileStorage.buckets.userFiles, and the mobile app uploads the objects directly to that bucket or container.

This changes the mobile image write path. Previously, mobile WebP bytes were sent through the normal LogRocket ingestion endpoint as part of the session event stream, so replay did not need to fetch those mobile image assets from userFiles. With async mobile upload, app clients also need to be able to reach the object storage upload endpoint and use the signed write URLs.

Replay also needs browser-reachable URLs for async-uploaded assets. If browsers cannot fetch from that URL because of routing, permissions, or CORS, sessions can still be replayed and all session data is uploaded correctly by the SDK, but async-uploaded assets cannot be hydrated during replay and affected recordings will contain missing images until the replay asset URL is fixed.

Review this before upgrading if your storage policy restricts reads or writes to cluster IAM roles, internal networks, VPC endpoints, source IPs, or other custom conditions. If your environment cannot allow direct signed uploads from app clients, disable async image upload in the mobile SDK configuration before recording sessions. For Android, call setEnableAsyncImageUpload(false) on the LogRocket configuration object before initializing the SDK.

Standard Chart Behavior

The chart automatically derives the primary replay asset prefix for standard storage providers:

  • GCP: https://storage.googleapis.com/<userFiles-bucket>/
  • AWS virtual-hosted S3: https://<userFiles-bucket>.s3.<region>.amazonaws.com/
  • AWS path-style S3: https://s3[-<region>].amazonaws.com/<userFiles-bucket>/
  • Azure Blob Storage: https://<storage-account>.blob.<endpoint-suffix>/<userFiles-container>/

For standard S3 URLs, the chart derives the replay prefix from fileStorage.buckets.userFiles, aws.region, and aws.useVirtualHostS3.

Azure Blob Storage must also have Blob service CORS configured for the userFiles container URL. If your LogRocket bootstrap Jobs do not manage this storage configuration, allow browser GET, HEAD, and OPTIONS requests from the LogRocket dashboard origin.

Additional Prefixes

Use cachedAssetPrefixes only when replay should fetch async-uploaded assets from a browser URL that differs from the standard derived prefix. Do not add the primary userFiles URL for standard GCP, AWS, or Azure storage.

The prefix must include the full path before the asset hash and must end with a trailing slash:

cachedAssetPrefixes:
  - 'https://cdn.example.com/logrocket-user-files/'
  - 'https://storage.googleapis.com/<legacy-userFiles-bucket>/'

Common cases include:

  • A CDN or proxy in front of object storage.
  • A custom S3-compatible endpoint.
  • A legacy or migrated user files bucket.
  • A storage URL that differs from the provider's default public URL.

Apply The Change

  1. Follow the normal LogRocket upgrade process to upgrade the Helm chart to the released version that includes backend ingest and automatic cached asset prefix configuration.
  2. If you use a CDN, proxy, custom S3 endpoint, or legacy bucket, add only those additional browser-reachable URLs to cachedAssetPrefixes as described above.
  3. Record or open a session from after the upgrade with the latest mobile SDK that contains cached canvas/image assets, then verify replay loads the assets without browser console CORS or 404 errors.

Rollback

If direct signed uploads cannot be supported, disable async image upload in the mobile SDK before recording new sessions. If you also need to disable the backend route and replay asset prefixes, set backendIngest.enabled to false and remove any custom cachedAssetPrefixes entries through the normal deployment process.

Updated about 8 hours ago