Links
What a link holds, how its URLs are built, the short-code rules, the preview page, clicks and the monthly quota.
Fields
| Field | What it's for |
|---|---|
fullUrl | Where the link leads inside your app. Your app routes by its path and query. |
title, description, imageUrl | The link's preview page and the cards chats and social networks show. |
fallbackUrl | Where the preview page sends computers, and phones whose platform has no store listing for your app. |
customShortCode | Your own short code instead of a generated one. |
title, description, imageUrl and fallbackUrl are required in every request but may be empty strings. Links are created and updated with POST /api/links and PUT /api/links/{id}, or in the dashboard.
How the URLs are built
You send fullUrl as a path, /products/1234, or as a URL on your link host or on one of your custom domains. Deep Blue Links keeps the path and query and builds:
- The full URL:
https://{app}.dev.thedbl.ink/products/1234. - The short URL:
https://{app}.dev.thedbl.ink/Xy3kP9aQ, orhttps://link.example.com/Xy3kP9aQwhenfullUrlwas on your custom domainlink.example.com.
A fullUrl on any other host answers 400.
Short codes
A generated code is 8 URL-safe characters. A custom code is 1 to 64 characters without whitespace or any of / ? # % \, and can't be . or .., so handles such as jane.doe or @jane work. A code already in use answers 400.
The preview page
Opening a short URL in a browser shows a page with your app's icon and name from the App Store, the link's image, title and description, a main button, and App Store and Google Play buttons. Without a title it reads "Open in" and your app's name.
After 1.5 seconds the page moves iPhones and iPads to the App Store, Android phones to Google Play and anything else to the fallback URL, and uses the fallback URL when your app has no store listing for the platform. Tapping a button, or leaving the page, cancels the move. The main button opens your app through its URL scheme when it has one.
The page also records the click for deferred deep links. URLs in imageUrl and fallbackUrl that aren't http or https are left out of the page.
When your app is installed and set up for the link host, iOS and Android open it directly and the page never shows.
Opening a link in your app
Your app receives the URL that opened it and sends it to POST /api/links/resolve, which answers with the link's id, longUrl and shortUrl. Route by the path and query of longUrl.
A full URL opens your app as well, because it's on the same host. If resolve answers 404, the URL isn't one of your short links: route by the URL itself.
Clicks
A click is recorded each time your app resolves a link: through resolve, GET /api/links/{id} or check-deferred. Opening the preview page in a browser isn't counted.
Quota
Your plan sets how many links your organization's apps can create each UTC calendar month, sandbox links included. Once they're used up, creating a link answers 400 until the next month or a plan change, and the organization's owner gets an email when 90% are used.
Updating and deleting
PUT /api/links/{id} replaces every field of a link, and DELETE /api/links/{id} deletes it for good, so its short URL stops working.