Minimal example app that shows an app-to-app customer app integration workflow with magicplan.

• Opens magicplan to create or reopen a linked project
• Receives a single .magicplan package back from the iOS share sheet
• Matches the package to a job by external_reference_id, with projectId as a fallback
• Replaces the previous import and surfaces project, form, space, and media data

Outbound from Field App:

magicplanstd://project/{projectId}
magicplanstd://create-project?name={jobTitle}&external_reference_id={jobId}&address_1={street}&city={city}&zip={postalCode}&country={country}&latitude={latitude}&longitude={longitude}

Inbound from magicplan:

application/vnd.magicplan.project-package+zip

The shared .magicplan archive contains manifest.json plus the referenced media files.

1. Open JB-24018 Alder Street Duplex.
2. Tap Create and open in magicplan.
3. In magicplan, capture the plan and documentation.
4. Use Share to Customer App and choose Field App.
5. Return to the job and review the imported data.

JB-24027 Maple Crest Residence already includes a sample import for a faster walkthrough.

For your app to appear as a share target when magicplan opens the iOS share sheet, you need three things:

In your app's Info.plist, declare that your app understands the com.magicplan.project-package type. Use UTImportedTypeDeclarations (not Exported — magicplan owns the type definition):

<key>UTImportedTypeDeclarations</key>
<array>
  <dict>
    <key>UTTypeIdentifier</key>
    <string>com.magicplan.project-package</string>
    <key>UTTypeDescription</key>
    <string>magicplan Project Package</string>
    <key>UTTypeConformsTo</key>
    <array>
      <string>public.zip-archive</string>
      <string>public.data</string>
    </array>
    <key>UTTypeTagSpecification</key>
    <dict>
      <key>public.filename-extension</key>
      <array>
        <string>magicplan</string>
      </array>
      <key>public.mime-type</key>
      <string>application/vnd.magicplan.project-package+zip</string>
    </dict>
  </dict>
</array>

Add a CFBundleDocumentTypes entry so iOS routes .magicplan files to your app:

<key>CFBundleDocumentTypes</key>
<array>
  <dict>
    <key>CFBundleTypeName</key>
    <string>magicplan Project Package</string>
    <key>CFBundleTypeRole</key>
    <string>Viewer</string>
    <key>LSHandlerRank</key>
    <string>Default</string>
    <key>LSItemContentTypes</key>
    <array>
      <string>com.magicplan.project-package</string>
    </array>
  </dict>
</array>

When the user picks your app from the share sheet, iOS delivers a file URL to your AppDelegate via application(_:open:options:). The file is a zip archive with a .magicplan extension. Your app should:

1. Copy the file into your sandbox (the source URL is a security-scoped temporary path).
2. Unzip it (this example uses SSZipArchive).
3. Read manifest.json from the extracted contents — this is the payload.
4. Resolve referenced media and thumbnail files from the same extracted directory.

See AppDelegate.swift for the full native implementation.

A .magicplan file is a standard zip archive containing:

Floor and room thumbnails are generated assets — they are not part of media_files. They are referenced by the image field on floor and room objects.

The payload follows schema version 1.0. All timestamps use the format YYYY-MM-DDTHH:MM:SS.ssssss+00:00.

{
  "schema_version": "1.0",
  "data": { /* project + plan */ }
}

Every user-captured photo, 360 photo, and video in the package appears here. Custom-form image attachments and autoscan/model media are excluded.

These objects appear at plan, floor, and room level. They share the same keys:

In statistics, values are numbers in metric base units. In statistics_formatted, values are display strings (e.g. "25 m2", "82 sq ft"). Both are sparse — only populated keys are present.

Line items come from the project's scope of work. They are keyed to the floor or room they belong to.

A simple key-value pair used for entity-level fields. Notes are always delivered through values (not top-level fields).

{ "id": "notes", "value": "Water damage along baseboard" }

Common value IDs:

Forms from the Forms tab. Only fields with user-filled values are included.

{
  "symbol_instance_id": "plan",       // which entity this form is attached to
  "symbol_type": "plan",              // "plan", "floor", "room", "wall_item", "furniture"
  "symbol_name": "My Project",
  "forms": [
    {
      "id": "abc-123",                // form template UUID
      "title": "Mitigation Checklist",
      "sections": [
        {
          "id": "abc-123s1",
          "name": "General",
          "fields": [
            {
              "id": "qf.moisture_level",
              "type_as_string": "number",
              "label": "Moisture level",
              "is_required": false,
              "value": {
                "has_value": true,
                "value": "42",
                "values": [],
                "formatted": null
              }
            }
          ]
        }
      ]
    }
  ]
}

Field type_as_string values: text, multitext, list, multilist, number, bool, distance, area, date, time, color, label, signature, image, image360, disclosure, illustration.

For multi-select fields, individual selections are in value.values[] and value.value is the comma-joined string.

Custom attribute forms from the Details tab (distinct from Forms tab forms). These map to the magicplan Cloud API's /projects/{id}/plan attributes endpoint.

{
  "symbol_instance_id": "room-1",
  "symbol_type": "room",
  "symbol_name": "Living Room",
  "custom_attributes": {
    "id": "qfield_title.abc-123",
    "title": "Room Details",
    "fields": [
      {
        "id": "qcustomfield.flooring_type",
        "type_as_string": "list",
        "label": "Flooring type",
        "is_required": false,
        "value": {
          "has_value": true,
          "value": "Hardwood",
          "values": [],
          "formatted": null
        }
      }
    ]
  }
}

Media files are assigned to entities using media_ids arrays that reference id values in data.media_files[]. The ownership model follows magicplan's Photos UI:

• Project-level: data.media_ids — photos not tied to a specific entity
• Entity-level: floor.media_ids, room.media_ids, wall.media_ids, object.media_ids — photos attached to that entity
• Fallback: If a photo's target entity no longer exists in the plan, it falls back to project-level

To resolve a media file to its actual bytes, look up the filename from media_files[] and find the matching file in the extracted zip directory.

npm install
bundle install
npm run ios:pods
npm start
npm run ios

npx tsc --noEmit
npm test -- --runInBand
xcodebuild -workspace ios/CustomerFieldApp.xcworkspace -scheme CustomerFieldApp -configuration Debug -destination 'generic/platform=iOS Simulator' CODE_SIGNING_ALLOWED=NO build