Using Blue Jetty with publisher-managed links
Use a publisher-approved HTTPS destination when your link service is not covered by a named Blue Jetty adapter. Blue Jetty can publish the URL and the experience it represents without guessing the provider's tracking or routing contract.
Download agent guide · Download complete configuration
Obtain a publishable URL from your link service
Configure the target app experience, supported platforms and fallback destinations in your existing service. Obtain a durable public URL from that service. Do not submit a dashboard URL, private API endpoint, temporary login link or link containing personalized identifiers.
Select an execution kind that describes the link
Use kind=attribution_link with provider=other for an existing attribution service whose link should pass through unchanged. Use kind=web for a web destination, or the appropriate native kind for a verified app-owned HTTPS route. Selecting other does not establish that the URL performs attribution or deferred deep linking.
A branded domain can also retain its known provider label while remaining unchanged when Blue Jetty does not recognize its host. Unknown hosts are not automatically registered as provider adapters; naming a provider never proves app ownership.
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://links.swell-atlas.example/spots",
"installState": "any",
"attribution": {
"provider": "other",
"campaign": "app_discovery",
"decoration": "preserve"
}
},
{
"id": "web-fallback",
"platform": "web",
"kind": "attribution_link",
"url": "https://links.swell-atlas.example/spots",
"installState": "any",
"attribution": {
"provider": "other",
"campaign": "app_discovery",
"decoration": "preserve"
}
}
]
}
],
"platformDefaults": [],
"promotions": []
}Configure parameters in the publisher's service
The other adapter adds no parameters, including when append_missing is requested. Use decoration=preserve and supply the final approved URL. Obtain reporting keys, signing requirements and deep-link behavior from your provider; do not borrow another provider's parameter names or ask a crawler to invent them.
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 against the publisher's own link contract
Compare the selected handoff URL with the original URL byte for byte. Test the actual installed, uninstalled and desktop journeys your service supports, including any signed-URL or expiration behavior. Store any confidential test evidence outside the public configuration.
If the service requires a personalized or secret-bearing URL, that URL is not suitable for a public Blue Jetty packet. Publish a stable public entry point instead. Provider capabilities remain unspecified for other; only the publisher's own service and device tests can establish its behavior.
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.