Skip to main content

Sharing & Deep Links

Blueprint supports sharing links to Work Items, Operator Rounds, and Routes across web and mobile platforms. When a user clicks a shared link, they're taken directly to the relevant content—whether in a web browser or the native mobile app.

EntityURL PatternExample
Work Item/work-items/{id}https://demo.cyzag.co/work-items/123
Operator Round/operator-rounds/{id}https://demo.cyzag.co/operator-rounds/456
Route/routes/{id}https://demo.cyzag.co/routes/789

Both integer IDs and UUIDs are supported in URLs. The web app automatically resolves UUIDs to their corresponding entities.

How It Works​

Web Browser​

When a user clicks a shared link:

  1. The browser navigates to the URL
  2. If not authenticated, they're redirected to sign in
  3. After sign-in, they return to the original link (return URL is preserved)
  4. The entity details page is displayed

Mobile App (Installed)​

When a user clicks a shared link on a device with the app installed:

  1. Android: App Links open the link directly in the app
  2. iOS: Universal Links open the link directly in the app
  3. The app navigates to the entity details screen

Mobile Browser (No App)​

When clicking a link on mobile without the app:

  1. The link opens in the mobile browser
  2. The web experience is displayed
  3. A future enhancement will show an app install banner

Each detail page includes a Copy Link button in the header toolbar:

  • Work Item Details: Click the link icon next to Edit/Delete
  • Operator Round Details: Click the link icon next to Edit/Delete
  • Route Details: Click the link icon next to Edit/Delete

The button copies a shareable URL (using the entity's UUID) to the clipboard. A checkmark appears briefly to confirm the copy action.

Social Sharing Previews​

When sharing links in Slack, Microsoft Teams, or other platforms that support Open Graph previews, a generic preview card is displayed:

┌─────────────────────────────────────┐
│ Cyzag Blueprint                     │
│ Industrial asset monitoring and     │
│ operator rounds platform            │
│ demo.cyzag.co                       │
└─────────────────────────────────────┘
Why generic previews?

All Blueprint data requires authentication. Social media crawlers cannot fetch entity-specific details without exposing data publicly. The generic preview identifies the link as a Blueprint resource; users see the full content after signing in.

Security​

All shared links require authentication:

  1. Authentication Required: Users must sign in to view any linked content
  2. Permission Enforcement: After authentication, the system verifies the user has permission to view the entity
  3. Tenant Isolation: Links only work within the user's authorized tenant

Error States​

ScenarioDisplayed Message
Entity not found"The item you're looking for doesn't exist or may have been moved."
Entity deleted"This item has been deleted and is no longer available."
No permission"You don't have permission to view this item."

Multi-Tenant Support​

Blueprint is a multi-tenant application. Deep links work across all tenant subdomains:

  • https://demo.cyzag.co/work-items/123
  • https://acme.cyzag.co/work-items/456
  • https://blueprint.cyzag.co/operator-rounds/789

Both Android App Links and iOS Universal Links are configured with wildcard domains (*.cyzag.co) to support any tenant subdomain.

Android App Links provide verified deep linking without user prompts. The app handles URLs matching:

https://*.cyzag.co/work-items/*
https://*.cyzag.co/operator-rounds/*
https://*.cyzag.co/routes/*

Domain verification is provided by /.well-known/assetlinks.json, which contains the app's signing certificate fingerprints for both debug and release builds.

iOS Universal Links provide seamless web-to-app handoff. The app is configured with:

  • Associated Domains entitlement: applinks:*.cyzag.co
  • Domain verification via /.well-known/apple-app-site-association

The verification files are served from Azure Blob Storage alongside the web application, ensuring all tenant subdomains return the same configuration.

Offline Behavior​

When a mobile app receives a deep link while offline:

  1. The app checks the local database for the entity
  2. If found locally, the cached data is displayed
  3. If not found, an error message is shown: "Item not cached. Will load when online."
  4. When connectivity returns, the app fetches the latest data

Future Enhancements (Phase 2)​

The following features are planned for future releases:

  • Action Links: Links that trigger specific actions (e.g., /routes/123/start-round)
  • Filtered View Links: Links with query parameters (e.g., /work-items?assignedTo=me)
  • QR Codes: Generate QR codes for assets that link to their rounds/work items
  • Smart App Banners: Prompt mobile web users to install the app
  • Share as Snapshot: Export a static PDF/JSON representation for offline sharing