Using Blue Jetty with Universal Links and Android App Links
Publish an app-owned HTTPS route as the destination for a relevant experience. iOS Universal Links and Android App Links associate that website with your installed app. Blue Jetty describes which route to use; it does not host the association files or add a mobile attribution service.
Download agent guide · Download complete configuration
Associate the website with the installed app
For iOS, configure the app's Associated Domains entitlement and the matching apple-app-site-association (AASA) file on the link's domain. Implement app-side handling for the associated URLs and paths.
For Android, configure verified App Link intent filters and publish /.well-known/assetlinks.json with the package name and signing-certificate fingerprint. The app must handle the requested path after Android opens it.
Use a concrete route, not an association-file URL
Submit a public HTTPS destination such as https://yourdomain.example/spots. AASA and assetlinks.json describe app/domain associations; they are not the destination a user should open and do not describe the full app experience.
The example uses platform=ios and kind=universal_link. For Android, add a separately identified execution with platform=android and kind=android_app_link after registering the Android app. Retain a usable web or store fallback for contexts where the native app cannot open. Native association alone does not provide deferred post-install routing.
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": "native_first",
"entityIds": [],
"executions": [
{
"id": "ios-open",
"platform": "ios",
"kind": "universal_link",
"url": "https://swell-atlas.example/spots",
"installState": "any"
},
{
"id": "web-fallback",
"platform": "web",
"kind": "web",
"url": "https://swell-atlas.example/spots",
"installState": "any"
}
]
}
],
"platformDefaults": [],
"promotions": []
}Keep the native URL unchanged
Native executions need no attribution object. Blue Jetty does not add MMP campaign parameters to a Universal Link or Android App Link. Preserve any public route or web-analytics parameters your app already understands; keep user-specific tokens and private data out of published URLs.
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 operating-system association and the route handler
Test a real tap from an external app or browser on installed devices, then verify the screen reached. Also test without the app installed and confirm the web/store fallback. Browser context and user link preferences can affect whether an associated URL opens the app.
On Android, adb shell pm get-app-links PACKAGE_NAME reports the device's domain verification state. If a link stays in the browser, inspect the association file, signing identity and device state. If the app opens the wrong screen, inspect the app's route handler. An HTTP 200 for the website does not exercise either step.
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.
Optional assistant-assembled routing choices
Configuration 0.5 can describe finite path-segment or query choices on an app-owned HTTPS execution. An assistant can assemble those choices locally using the published rules and examples. Your existing Universal/App Link handling must support the resulting routes.
Recipes are optional; the concrete execution URL remains the fallback. Review the exact grammar, boundaries and configuration example before enabling this additional permission. Syntax validation is separate from device testing.
Blue Jetty references
Configuration 0.5 schema · API endpoints · Device-test guide
Provider names describe existing-link compatibility, not affiliation or endorsement.