ExtlClntAppPushSettings Metadata in Salesforce

Architectural Overview#

ExtlClntAppPushSettings defines the developer-side push messaging technical infrastructure within the Salesforce External Client App ecosystem. When mobile software developers build enterprise applications that rely on mobile alerts, the Salesforce platform must be equipped with the appropriate network routes, cryptographic signatures, and gateway parameters to interface with Apple (APNs) and Google (FCM).

In legacy Connected Apps, push certificates and gateway settings were inextricably bound with OAuth secrets and admin permissions. ExtlClntAppPushSettings extracts developer push infrastructure into a self-contained metadata entity. Developers specify whether Apple APNs or Google FCM is supported, define push gateway endpoints, and register token lifespans.

This clean architecture allows developers to update push infrastructure parameters across development sandboxes and 2GP packaging pipelines without impacting the operational policies managed by subscriber administrators.

Directory and File Conventions#

ExtlClntAppPushSettings metadata files reside within the extlClntAppPushSettings directory:

Key Metadata Fields#

The ExtlClntAppPushSettings schema exposes the following technical configuration attributes:

Declarative XML and Package Manifest Examples#

Below is a declarative XML definition of ExtlClntAppPushSettings configured for a multi-platform enterprise mobile deployment:

<?xml version="1.0" encoding="UTF-8"?>
<ExtlClntAppPushSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <developerName>Logistics_Mobile_Push</developerName>
    <isApplePushSupported>true</isApplePushSupported>
    <isFcmPushSupported>true</isFcmPushSupported>
    <pushEndpointUrl>https://push-relay.enterprise-logistics.com/v1/dispatch</pushEndpointUrl>
    <tokenExpirationMinutes>10080</tokenExpirationMinutes>
</ExtlClntAppPushSettings>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Logistics_Mobile_Push</members>
        <name>ExtlClntAppPushSettings</name>
    </types>
    <version>68.0</version>
</Package>

CLI Retrieval and Deployment Commands#

Retrieve and deploy push settings metadata using the Salesforce CLI:

# Retrieve push settings for a specific client application
sf project retrieve start --metadata ExtlClntAppPushSettings:Logistics_Mobile_Push

# Deploy push settings to target sandbox
sf project deploy start --metadata ExtlClntAppPushSettings:Logistics_Mobile_Push

# Retrieve all push components across the project
sf project retrieve start --metadata "ExtlClntAppPushSettings,ExtlClntAppPushConfigurablePolicies"

Architect Best Practices and Gotchas#

• FCM HTTP v1 Migration: Ensure external push integration gateways utilize Google Firebase Cloud Messaging HTTP v1 API. Legacy FCM API keys are deprecated; token exchanges must be negotiated via OAuth 2.0 service account credentials.
• Token Cache Alignment: Align tokenExpirationMinutes with the token refresh interval implemented in your native mobile application binary. A mismatch can result in push delivery attempts against stale, invalidated device tokens.
• Proxy Gateway Resiliency: If deploying a custom pushEndpointUrl, design the proxy gateway to handle bursty spikes resulting from automated bulk record updates or mass notification dispatches.

Frequently asked questions

What is configured in ExtlClntAppPushSettings metadata?

ExtlClntAppPushSettings defines the developer-side push messaging configuration including APNs gateway endpoints, FCM project IDs, and service flags.

How does ExtlClntAppPushSettings integrate with Apple Push Notification service?

It configures the APNs production or sandbox gateway endpoints, team identifiers, and encryption keys required to deliver iOS push payloads.

Why is push notification configuration split between Settings and Policies?

Settings contain developer-defined infrastructure endpoints, while Policies give subscriber org admins control over notification execution and quotas.

How do you retrieve ExtlClntAppPushSettings using the sf CLI?

Run sf project retrieve start with metadata set to ExtlClntAppPushSettings to extract the push settings into your local workspace.