Mobile Push Notifications

Starting with version 6.5.6, the CommuniGate Pro Server sends push notifications to mobile devices (iOS via APNs, Android via Firebase Cloud Messaging HTTP v1 API). Settings for each mobile application are stored in a pushparams-<appName>.settings file uploaded to the Real-Time Application Environment (PBXApps).

The <appName> value must match the appName field in the user's DeviceTokens record.

Placing the Settings File

Upload pushparams-<appName>.settings to PBXApps:

the server-wide Environment — if settings are the same for all domains;
a domain Environment — if different domains use different mobile apps or credentials.

The Server looks in the domain Environment first, then in the server-wide Environment. See Real-Time Applications for PBXApps access details.

The bearer-token preparation script pushprepare.scgp must be present in WebSkins (shipped with the Server).

General Structure

text

{
  EventSubscription = (incomingEmail);
  SettingsScript = pushprepare.scgp;

  APNsServiceData = { ... };   // iOS, optional block
  FCMServiceData = { ... };    // Android, optional block
}

Parameter	Description
`EventSubscription`	List of Server events the application is subscribed to. A push is sent only if the event is in this list.
`SettingsScript`	Name of the CG/PL script in WebSkins that obtains bearer tokens for APNs and FCM. Usually `pushprepare.scgp`.
`APNsServiceData`	Apple Push Notification service authentication data. Omit this block if iOS is not used.
`FCMServiceData`	Firebase service account data. Omit this block if Android is not used.

The APNsBearerToken and FCMBearerToken keys are not set manually — they are added by pushprepare.scgp at send time.

Supported Events

The Server can send push notifications for the following events (the full list is defined by the pushhandler application):

Event	Purpose
`incomingEmail`	Incoming mail message
`incomingIM`	Incoming instant message
`incomingCall`	Incoming call
`incomingSubscribe`	Subscription request
`incomingInfo`	Incoming invitation (Info)
`textMessage`	Text message
`x2authPush`	Two-factor authentication (code)
`x2authBio`	Two-factor authentication (biometrics)
`unlockSMIME`	S/MIME unlock
`messenger`	Messenger application events

For a mail client, incomingEmail is usually sufficient. For a client with call support, add incomingCall and other required events.

iOS Configuration (APNs)

Obtain credentials from Apple Developer: create an APNs key (.p8 file) and copy the Key ID and Team ID.

Parameter	Setup	Description
`private_key`	required	Contents of the `.p8` key as a single string; use `\n` for line breaks.
`key_id`	required	APNs Key ID (10 characters).
`team_id`	required	Apple Developer Team ID.
`bundle_id`	required	iOS application bundle identifier (used as `apns-topic` when sending).
`is_development`	required	`YES` — sandbox (debug, dev builds), `NO` — production (App Store, prod builds). Must match the device token type registered by the client.
`api_host_development`	usually unchanged	APNs sandbox host. Default: `api.sandbox.push.apple.com`.
`api_host_production`	usually unchanged	APNs production host. Default: `api.push.apple.com`.

Android Configuration (FCM)

Recommended approach: in the Firebase console, open Project settings → Service accounts → Generate new private key, download the service account JSON, and copy its fields into FCMServiceData.

Parameter	Setup	Description
`type`	copy from JSON	Always `service_account`.
`project_id`	required	Firebase project ID (used in the FCM v1 API URL).
`private_key_id`	required	Private key identifier from JSON.
`private_key`	required	Private key from JSON; paste as a single string with `\n`.
`client_email`	required	Service account e-mail (`firebase-adminsdk-…@….iam.gserviceaccount.com`).
`client_id`	copy from JSON	Client identifier.
`auth_uri`	copy from JSON	Standard Google OAuth URL.
`token_uri`	copy from JSON	Standard URL (`https://oauth2.googleapis.com/token`).
`auth_provider_x509_cert_url`	copy from JSON	Google certificates URL.
`client_x509_cert_url`	copy from JSON	Service account metadata URL (must match `client_email`).
`universe_domain`	copy from JSON	Usually `googleapis.com`.

Configuration Example

Example for an application named cgp:

text

{
  // Server events the application is subscribed to. A push is sent only if the event
  // is in this list. The list of supported events is in pushutils.sppi (supportedEvents).
  EventSubscription = (incomingEmail);

  // Script that obtains bearer tokens for FCM and APNs (pushprepare.scgp in WebSkins).
  // Leave unchanged if you use the standard authentication scheme.
  SettingsScript = pushprepare.scgp;

  // --- iOS (Apple Push Notification service) ---
  // Omit this block entirely if the iOS application is not used.
  APNsServiceData = {
    // REQUIRED: contents of the .p8 key from Apple Developer (Certificates, Identifiers & Profiles → Keys).
    // Paste as a single string; use \n for line breaks.
    private_key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n";

    // REQUIRED: APNs Key ID (10 characters), shown next to the .p8 key in Apple Developer.
    key_id = "Key_ID";

    // REQUIRED: Apple Developer organization Team ID.
    team_id = "Team_ID";

    // REQUIRED: iOS application bundle identifier (used as apns-topic when sending).
    bundle_id = "com.example.app";

    // REQUIRED: YES — sandbox (debug/TestFlight dev builds), NO — production (App Store / prod builds).
    // Must match the device token type registered by the client.
    is_development = YES;

    // Usually leave unchanged: APNs sandbox host.
    api_host_development = "api.sandbox.push.apple.com";

    // Usually leave unchanged: APNs production host.
    api_host_production = "api.push.apple.com";
  };

  // --- Android (Firebase Cloud Messaging HTTP v1 API) ---
  // Omit this block entirely if the Android application is not used.
  FCMServiceData = {
    // Copy as-is from the Firebase JSON.
    type = service_account;

    // REQUIRED: Firebase project ID (used in the FCM v1 send URL).
    project_id = my-firebase-project;

    // REQUIRED: private key identifier from the service account JSON.
    private_key_id = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa;

    // REQUIRED: private key from JSON; paste as a single string with \n.
    private_key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n";

    // REQUIRED: service account e-mail from JSON (firebase-adminsdk-…@….iam.gserviceaccount.com).
    client_email = "firebase-adminsdk-aaaaa@my-firebase-project.iam.gserviceaccount.com";

    // Copy as-is from the Firebase JSON.
    client_id = "123456789012345678901";

    // Copy as-is from the Firebase JSON (standard Google OAuth URL).
    auth_uri = "https://accounts.google.com/o/oauth2/auth";

    // Copy as-is from the Firebase JSON (standard URL; required for settings validation).
    token_uri = "https://oauth2.googleapis.com/token";

    // Copy as-is from the Firebase JSON.
    auth_provider_x509_cert_url = "https://www.googleapis.com/oauth2/v1/certs";

    // Copy as-is from the Firebase JSON (URL must match client_email).
    client_x509_cert_url = "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-aaaaa%40my-firebase-project.iam.gserviceaccount.com";

    // Copy as-is from the Firebase JSON.
    universe_domain = "googleapis.com";
  };
}

The file must be named pushparams-cgp.settings and uploaded to PBXApps.

Upgrading from Earlier Versions

Important when upgrading to 6.5.6

Application settings moved from WebSkins/pushparams-<app>.objdata to PBXApps/pushparams-<app>.settings. Legacy WebSkins files are not read — pushes stop working until migrated.

When upgrading from versions before 6.5.3:

Android: replace the FCMKey (legacy server key) with an FCMServiceData block (Firebase service account) and add SettingsScript = pushprepare.scgp.
iOS: replace APNsKey / APNsCert with an APNsServiceData block.

Do not set FCMBearerToken manually — pushprepare.scgp obtains and caches it automatically.

Troubleshooting

If push notifications do not work, verify:

pushparams-<appName>.settings is uploaded to the correct PBXApps Environment (domain or server-wide).
The application name in the file matches appName in the user's DeviceTokens.
The required event is listed in EventSubscription.
The pushprepare.scgp script is present in WebSkins.
For iOS: is_development matches the client build type; bundle_id matches the application.
For Android: the Firebase service account has permission to send messages (Firebase Cloud Messaging API).

Authentication errors are logged in the System Log with pushprepare and PushHandler tags.

Mobile Push Notifications ​

Placing the Settings File ​

General Structure ​

Supported Events ​

iOS Configuration (APNs) ​

Android Configuration (FCM) ​

Configuration Example ​

Upgrading from Earlier Versions ​

Troubleshooting ​