Migration from 2.3.x to 2.4.x

This guide provides instructions for migrating from Wultra Mobile Token SDK for iOS version 2.3.x to version 2.4.x.

Version 2.4.x introduces a new, extensible Pre‑approval UI Template and replaces the legacy singular screen with a plural model. The goal is to make the UI configurable (images/icons/buttons/alerts) while keeping app code simple.


Added Functionality

  1. Multiple Pre‑approval Screens
    The singular preApprovalScreen is replaced by preApprovalScreens: [WMTPreApprovalScreen].

  2. New Screen Fields
    Each screen may now specify:
    • id: String? - unique identifier for the screen
    • backButton: Bool? - when true, show a back button in navigation bar instead of using decline as “back”
    • image: String? - asset identifier to be mapped in the app
  3. Structured Screen Content
    Each screen can include typed elements (LIST_ITEM, ALERT, BUTTON) and configurable controls (approve/decline UI).

  4. Configurable Controls
    • decline is optional (type: BACK | REJECT, optional text)
    • approve is optional (type: SLIDER | BUTTON, optional text, optional counter). Apps should provide a default approve control if missing. The counter defines how long (in seconds) the approve control remains disabled after the screen appears.
    • axis: HORIZONTAL | VERTICAL and flip: Bool control layout order/stacking
  5. Configurable Visuals
    • Screen image and list item icon are resolved from app assets (e.g., SVG).
  6. Reject method
    • The OperationsService reject method now also accepts mobileTokenData, just like confirm. If applicable, these values should be attached to WMTOperation when calling confirm/reject methods.
  7. New RejectionReason
    • New rejection reason PREAPPROVAL indicates the user cancelled the operation during the Pre-Approval flow.

Removed / Changed Functionality

  1. Singular Pre‑approval Removed from WMTOperationUIData
    • Removed: preApprovalScreen (object with items and approvalType)
    • Replaced by: preApprovalScreens: [WMTPreApprovalScreen]
  2. Ad‑hoc Fields Removed
    • Removed: items: [String] → use elements with type: "LIST_ITEM" and text
    • Removed: approvalType → use controls.approve.type (SLIDER or BUTTON)
  3. Legacy Fallback Behavior
    • If plural is present, singular is ignored.
    • If plural is absent, the SDK still converts the legacy singular via fromLegacy, but your app’s model must be updated.

Server / JSON Migration

Before (2.3.x – singular):

{
  "flipButtons": true,
  "blockApprovalOnCall": false,
  "preApprovalScreen": {
    "type": "WARNING",
    "heading": "Watch out!",
    "message": "You may become a victim of an attack.",
    "items": [
      "You activate a new app and allow access to your accounts",
      "Make sure the activation takes place on your device",
      "If you have been prompted for this operation in connection with a payment, decline it"
    ],
    "approvalType": "SLIDER"
  }
}

After (2.4.x – plural):

{
  "flipButtons": true,
  "blockApprovalOnCall": false,
  "preApprovalScreens": [
    {
      "id": "custom_id",
      "type": "WARNING",
      "backButton": true,
      "image": "image-label",
      "heading": "Watch out!",
      "message": "You may become a victim of an attack.",
      "elements": [
        { "id": "e1", "type": "ALERT", "style": "INFO", "text": "Make sure the activation takes place on your device" },
        { "id": "e2", "type": "BUTTON", "action": "PHONE", "text": "Call center", "href": "+42012345678" },
        { "id": "e3", "type": "LIST_ITEM", "icon": "icon-label", "text": "You activate a new app and allow access to your accounts" }
      ],
      "controls": {
        "flip": true,
        "axis": "VERTICAL",
        "decline": { "type": "REJECT", "text": "Reject Payment" },
        "approve": { "type": "BUTTON", "text": "Approve Payment", "counter": 10 }
      }
    },
    {
      "id": "qr1",
      "type": "QR_SCAN",
      "heading": "Watch out!",
      "message": "You may become a victim of an attack."
    }
  ]
}

Migration Checklist

  • Replace preApprovalScreenpreApprovalScreens.
  • Replace itemselements of type LIST_ITEM.
  • Map approvalTypecontrols.approve.type.
  • Use id, backButton, image when present.
  • For ease of use, consider using new RejectionReason PREAPPROVAL when rejecting operations during pre-approval screens flow.

Last updated on Oct 10, 2025 (09:01) Edit on Github Send Feedback
Search

develop

Mobile Token SDK for iOS