Add the JSON to Xcode
Drag HaloIntegration.json into your project. Enable Copy items if needed and select the macOS app target.
Describe what your macOS app can do, what input each action accepts, what should activate it, and how Halo should deliver requests. The builder generates a HaloIntegration.json that matches Halo's current protocol-v2 decoder.
Optional metadata Halo can use to present your integration like a built-in Context Interface card.
Each action declares its own input contract and typed options. File actions must list accepted extensions because Halo uses them for drag eligibility.
Triggers decide when an integration becomes eligible. A fileDrag trigger must reference one or more file-input actions.
Current Halo builds deliver a temporary .halorequest plus the authorized input files through the normal macOS open-URL flow.
Discovery and invocation are separate. The manifest tells Halo what your app supports; your app still needs to receive the request and perform the declared action.
Drag HaloIntegration.json into your project. Enable Copy items if needed and select the macOS app target.
In Build Phases → Copy Bundle Resources, verify that HaloIntegration.json is present.
If your manifest declares a banner, add that image to the app target too. Recommended: 1200 × 540 PNG, with key content inside a 1040 × 420 safe area.
Register the .halorequest document type so macOS can deliver Halo's request envelope to your app.
Decode the request, resolve actionID, then perform the action using the other file URLs supplied in the same open request.
.halorequest receiver, Halo can still open/send files to your app, but your app will not know which declared action Halo requested.
presentation block is additive metadata. Current Halo protocol decoding safely ignores unknown fields, so manifests containing it remain compatible even before a Halo build consumes the partner-card artwork.
| Field | Type | Current behavior |
|---|---|---|
protocolVersion | Integer | Use 2 for new integrations. Halo still normalizes v1 for compatibility. |
app.name | String | Human-readable application name. |
app.bundleIdentifier | String | Must exactly match the containing macOS app bundle. |
presentation.card.bannerImage | String? | Optional bundle-resource filename for the partner CI card banner. Recommended artwork size: 1200 × 540 px. |
presentation.card.category | String? | Short card subtitle/category, up to 40 characters in this builder. |
presentation.card.description | String? | Short partner-facing CI description, up to 160 characters. |
presentation.card.accentColor | #RRGGBB? | Optional accent hint for the card. |
actions[].id | Identifier | Stable action identity used for configuration and delivery. |
actions[].input.type | none | files | Declares whether the action needs selected files. |
actions[].input.extensions | String[] | Required for functional file actions. No dots; * means any extension. |
actions[].input.multiple | Boolean | When false, a multi-file drag is not eligible for that action. |
actions[].options[].default | Typed value? | Optional default must match the option's declared type. |
triggers[].type | Enum | fileDrag, keyboardShortcut, manual, or schema-valid partnerEvent. |
triggers[].actions | String[] | References stable action IDs. fileDrag may reference only file-input actions. |
triggers[].eventName | Identifier? | Required for partnerEvent. External event ingress is not active yet. |
delivery.type | String | Current supported value: openRequest. |