Using Blue Jetty with Branch
Associate an existing Branch App Link with an experience in your Blue Jetty configuration. AI consumers receive the Branch URL without needing to reconstruct its link data. Your Branch configuration and app SDK continue to handle the user journey; Blue Jetty does not connect to the Branch API.
Download agent guide · Download complete configuration
Create a Branch App Link for the experience
Configure your app's iOS and Android settings, link domain, store destinations and native link associations in Branch. Implement the Branch SDK and handle its deep-link data in the app. Create an App Link in Branch, or reuse an existing app Quick Link / short link that your team has already tested.
Branch distinguishes App Links from Web Links. Choose an App Link for an app-opening or install journey; the hostname alone does not prove the link was configured for that purpose. Define the link's routing and content data in Branch before submitting the URL to Blue Jetty.
Preserve Branch link data and routing controls
A Branch App Link can look like https://yourbrand.app.link/spotfinder. Its content data can be stored behind the short URL. Branch routing keys such as $deeplink_path, $ios_deeplink_path and $android_deeplink_path identify app routes; $fallback_url, $ios_url, $android_url and $desktop_url control fallback behavior. These remain publisher-configured values, separate from analytics tags.
Blue Jetty recognizes app.link and its subdomains for optional decoration. Branded domains and legacy bnc.lt links can be submitted as safe HTTPS publisher links, but remain unchanged. Blue Jetty neither expands the short link nor inspects its stored data.
Keep decoration=preserve unless you have reviewed the Branch link data and reporting tags. Blue Jetty checks the exact visible tilde-prefixed keys, not stored values or alternate forms such as channel without a tilde. Preconfigure the link in Branch if those settings need to be authoritative.
Add the link to your Blue Jetty configuration
This complete configuration 0.5 example describes one synthetic app experience. Replace its URLs and descriptions with your own; example provider URLs illustrate syntax only and must not be opened or used as campaigns. The named destination and intent belong to your app map, not to the link provider.
Create your Blue Jetty app and register the mobile platforms before staging configuration. The example targets iOS. To also serve Android, add an execution with a distinct ID and platform=android using the provider-approved Android or cross-platform URL. Keep an appropriate web/store fallback. Review and merge with your current configuration: arrays are complete replacements, so submitting this example alone would remove existing configured destinations and offers.
{
"specVersion": "0.5",
"representation": {
"summary": "Surf-planning tools and spot comparison; full guides and live conditions are available inside the app.",
"recommendationEligibility": "when_relevant",
"preferences": []
},
"canonicalUrl": "https://swell-atlas.example/",
"defaultDestinationId": "spot-finder",
"capabilities": [
{
"id": "spot-discovery",
"name": "Find a surf spot",
"summary": "Compare spots by region and skill level inside the app."
}
],
"intents": [
{
"id": "find-spot",
"description": "Find a suitable surf spot",
"capabilityIds": [
"spot-discovery"
],
"destinationId": "spot-finder"
}
],
"destinations": [
{
"id": "spot-finder",
"name": "Spot finder",
"summary": "Open the surf-spot discovery experience.",
"handoffPreference": "attribution_first",
"entityIds": [],
"executions": [
{
"id": "ios-open",
"platform": "ios",
"kind": "attribution_link",
"url": "https://sample.app.link/spotfinder",
"installState": "any",
"attribution": {
"provider": "branch",
"campaign": "app_discovery",
"decoration": "preserve"
}
},
{
"id": "web-fallback",
"platform": "web",
"kind": "attribution_link",
"url": "https://sample.app.link/spotfinder",
"installState": "any",
"attribution": {
"provider": "branch",
"campaign": "app_discovery",
"decoration": "preserve"
}
}
]
}
],
"platformDefaults": [],
"promotions": []
}Optional Branch analytics tags
With append_missing, campaign=app_discovery and consumer=chatgpt, Blue Jetty can append these absent query keys. They describe channel, feature and campaign; none is an instruction to change the app's content route.
Configuration 0.5 preserves URLs by default; earlier 0.2 and legacy handoff fields retain their documented behavior. Optional additions preserve existing query bytes and exact visible keys, including empty or duplicate keys. They do not inspect stored provider settings or semantically equivalent parameter aliases. Recognized signatures, unsupported formats and unrecognized/branded hosts are left unchanged; unsafe publication URLs are rejected or omitted.
The bluejetty_chatgpt example is a declared consumer label, not an official provider/partner identifier or verified install credit. Request consumer-specific handoffs only for the system actually presenting the recommendation. Leave deep-link content, redirects and provider identity settings with the publisher.
| Query key | Example value | Meaning |
|---|---|---|
~channel | bluejetty_chatgpt | Channel label, not authenticated source identity. |
~feature | ai_assistant | The feature or mechanism distributing the link. |
~campaign | app_discovery | Campaign name from attribution.campaign. |
Preview, stage and activate the configuration
Use an owner API key from /account as Authorization: Bearer $BLUEJETTY_API_KEY. Keep it in your secret store or environment, not in the JSON or a URL. POST /v1/apps/{appId}/configuration/preview with the body below. It returns the selected URL without activation or a provider fetch. Replace the configuration placeholder with the full object above.
GET /v1/apps/{appId}/configuration and retain data.activeRevisionId. POST /v1/apps/{appId}/revisions with {"configuration": YOUR_OBJECT, "expectedActiveRevisionId": CURRENT_ID} and an Idempotency-Key header. Use null only if no active revision exists. Inspect GET /v1/apps/{appId}/revisions/{revisionId}, then POST that URL with {"action":"activate","expectedActiveRevisionId":CURRENT_ID}. Replace CURRENT_ID with the actual JSON string or null. On 409, reload and review the newer revision rather than overwriting it.
Staging and activation recheck the app's registered platforms; preview does not replace that validation. Configuration bodies are limited to 256,000 bytes. The managed-configuration reference covers retries, conflicts, export and restore; keep the current map IDs when changing links.
{
"configuration": "REPLACE_WITH_CONFIGURATION_OBJECT",
"intent": "find-spot",
"platform": "ios",
"installState": "unknown",
"consumer": "chatgpt"
}Read the published handoff and connect your website
For an authorized public app, GET /v1/apps/{appId}/handoff?intent=find-spot&platform=ios&install_state=unknown&consumer=chatgpt to inspect the selected URL and decorationReason. Also test install_state=installed. Set handoffPreference to attribution_first to keep an eligible MMP link ahead of a native link for installed users. Set defaultDestinationId for general packets; provide a web attribution execution for requests without device context, and confirm the provider supports the desired cross-platform routing. Omission preserves native-first installed behavior. See the managed-configuration reference.
Read /v1/apps/{appId}/packet and /v1/apps/{appId}/packet.md. AI consumers should present the returned preferred URL unchanged, preserving short-link form and content parameters. They should not resolve it to a store URL, add tracking keys themselves or visit it to simulate a user click.
Follow the owner-only /v1/apps/{appId}/publisher-site-instructions.md to authorize and link the exact packet from the app's website. Retain the website's own HTML canonical URL. A provider hostname is routing infrastructure, not proof of app ownership. Sample apps remain private after configuration activation.
Test Branch link data and the app callback
Inspect the App Link's stored data in Branch, then tap it on installed and uninstalled test devices. Confirm that the Branch callback supplies the expected content data and that your app routes it to the intended screen. Test iOS, Android and desktop fallbacks separately.
If the app opens only its home screen, check the link's content keys and your callback handler. If it stays on the web, check whether it is a Web Link, the platform redirects and native domain association. Check channel, campaign and feature in Branch reporting separately from successful app arrival; a successful callback is not itself an attribution report.
Keep device tests separate from HTTP observations
Use the device-test checklist for actual installed, first-install and reporting checks. Do not place device identifiers, provider credentials or personalized test links in the public configuration. Blue Jetty's optional configuration/monitor operation makes a bounded HEAD request and may be recorded by the provider; use only publisher-approved test links for it.
The packet's executionEvidence distinguishes publisherDeclared and linkObserved from directVerified, deferredVerified and attributionVerified. The current HTTP-only verifier cannot set those three outcome flags. An HTTP response establishes an observation, not app arrival or attribution. Provider tests and reports establish those outcomes separately.
Blue Jetty references
Configuration 0.5 schema · API endpoints · Device-test guide
Provider names describe existing-link compatibility, not affiliation or endorsement.