Skip to content

General Migration Considerations

The current native SDK uses the API v3 payload and a structured customization model. If your Android integration still depends on legacy flat UI keys, plan the migration before reusing old configuration blocks.

1. Backend request format

The authentication API used to obtain the access token can be called with either:

  • application/json
  • multipart/form-data

With multipart/form-data, the JSON payload remains the main data body and optional customization files can be attached separately:

  • texts
  • medias
  • styles

This is useful when product or localization teams manage large customization files independently from the main onboarding JSON.

Example:

payload = {
    "data": """
    {
        "platform": "android",
        "language": "en",
        "operationMode": "idv",
        "flowSetup": {
            "core": { "confirmProcess": true },
            "stages": ["document"]
        }
    }
    """
}

files = [
    ("texts", ("texts.json", open("/path/to/texts.json", "rb"), "application/json"))
]

Use one channel consistently: if a section is sent as a file, do not duplicate the same content inline in the root JSON.

2. Move from flat keys to structured sections

Legacy native configurations often mixed behavioral flags and visible content inside stage-specific setup blocks. The current model separates them:

  • Keep onboarding behavior in flowSetup.
  • Keep shared visibility flags in setup.
  • Move visible strings to texts.
  • Move reference assets to medias.
  • Move colors, fonts, and component tokens to styles.

Example

Legacy approach:

{
    "flowSetup": {
        "options": {
            "document": {
                "captures": [
                    {
                        "setup": {
                            "tutorial_show": "YES",
                            "tutorial_titleText": "Document Capture",
                            "tutorial_bodyText": "Center your document inside the frame"
                        }
                    }
                ]
            }
        }
    }
}

Current approach:

{
    "flowSetup": {
        "options": {
            "document": {
                "captures": [
                    {
                        "setup": {
                            "instructionsShow": true
                        }
                    }
                ]
            }
        }
    },
    "texts": {
        "document": [
            {
                "step": 1,
                "instructions": {
                    "obverse": {
                        "title": "Document Capture",
                        "subtitle": "Center your document inside the frame"
                    }
                }
            }
        ]
    }
}

3. Keep behavior close to the stage that uses it

Stage-specific behavior should remain in the relevant flowSetup.options branch. Typical examples are:

  • instructionsShow
  • capture options
  • document selector setup
  • per-stage feature toggles

This keeps product logic separate from branding.

4. Treat assets and copy as product content

Once the migration is complete, non-engineering teams can usually evolve copy and assets without touching behavioral configuration. This is one of the main reasons to adopt the V3 structure.

  1. Move flags that change behavior into flowSetup or setup.
  2. Move all visible strings into texts.
  3. Move logos and illustrations into medias.
  4. Recreate colors and component appearance in styles.
  5. Validate each stage on a physical iPhone before release.