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.
8. MobileTokenData Builder

• Introduced MobileTokenData.Builder, a helper for composing structured data attached to operations during authorization or rejection.
• Supports both generic key–value entries builder.put(key, value) and structured records such as WMTPreApprovalScreensRecorder builder.put(record).
• Structured records conform to the WMTMobileTokenDataRecord protocol (defines a stable key and a build() -> Encodable).
• builder.build() produces the [String: Encodable] dictionary to be assigned to operation.mobileTokenData.

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", "actionSettings": "REJECT", "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 preApprovalScreen → preApprovalScreens.
• Replace items → elements of type LIST_ITEM.
• Map approvalType → controls.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.