Push Notification Schema
========================


When Paytronix sends a push notification to a mobile device, the payload varies
slightly between Apple Push Notification service (APNs) and Firebase Cloud
Messaging (FCM/Android). Both platforms share a common logical structure based
on the ``PushData`` type.

Push notifications are triggered by campaign messages. The ``deepLink`` field,
when present, controls where the user is directed upon tapping the notification.


Push Payload Schema
~~~~~~~~~~~~~~~~~~~

.. http:jsonentity:: PushMessage

   Represents a standard push notification payload (``type: message``).

   :jsonparam String type: *(required)*  Always ``message`` for this payload type.
   :jsonparam String message: *(required)*  The main text content of the push notification displayed to the user.
   :jsonparam Object deepLink: *(optional)*  If available, specifies where the user should be directed when they interact with the notification. See :http:jsonentity:`DeepLink` for format of the object.


.. http:jsonentity:: DeepLink

   Describes the deep link destination for a push notification or inbox message.

   :jsonparam String typ: *(required)*  The type of deep link. One of ``AppScreen``, ``CategoryItem``, ``ExternalUrl``, ``MenuItem``, or ``Survey``.
   :jsonparam String value: *(required)*  The target value for the deep link (e.g. a screen name, external URL, or survey identifier).


APNs (Apple) Payload Notes
---------------------------

When delivering to Apple devices via APNs:

- The ``message`` field is sent as the alert body.
- The ``deepLink`` object, when resolved, is included as a custom APNs property
  named ``deepLink`` containing ``type`` and ``value`` fields.
- Badge number is set separately per device session.
- Maximum payload size: **1024 bytes**.
- Notification TTL: **48 hours**.
- Delivery priority: ``IMMEDIATE``.

See :ref:`push_ios` for flow details. 

FCM/GCM (Android) Payload Notes
---------------------------------

In FCM there are two distinct message types:

**Notification message** - FCM handles display automatically (title, body shown in system tray). The app doesn't need to do anything.

**Data message** - delivered as a key/value data bundle to the app, which must handle display itself.

Of these, Paytronix sends a ``Data message``. 

.. list-table::
   :header-rows: 1
   :widths: 20 15 65

   * - Key
     - Type
     - Description
   * - ``message``
     - String
     - *(required)*  The main text content of the push notification.
   * - ``deepLink``
     - String
     - *(optional)*  The resolved deep link encoded as a string, containing
       ``type`` and ``value`` fields. See :http:jsonentity:`DeepLink`.
   * - ``badgeNumber``
     - String
     - *(optional)*  The badge count to display on the app icon, serialised as
       a string.

Other delivery parameters (TTL, collapse key, idle-delay behaviour) are managed
internally by Paytronix and are not configurable by the merchant.

See :ref:`push_android` for flow details.