Giter VIP home page Giter VIP logo

x's Introduction

x

Documenting the History of x-callback-url and URL Schemes

The original specification

The x-callback-url specification is intended to standardize the use of URLs and registered URL schemes for inter-app communication and messaging on Apple’s iOS platforms.

Revisions

R3: Added “Security Concerns” section.

R2: Added optional “x-cancel” parameter. When supported, this parameter would include a URL to open when the user indicated they want to cancel the action. The action did not succeed, nor generate an error, but the user just wishes to return to the source app.

R1: Removed the “version” from the URL path. The current recommendation if versioning of an x-callback-url API is required would be to register separate URL schemes for each version. This method allows the calling app to determine which versions are available via calls to “canOpenURL”.

Discussion

iOS runs apps in sandboxes which providing limited means of communication between apps directly on the device. Shared files, messaging systems and other similar solutions used on desktop and server operating systems are not present in iOS.

iOS does provide the ability for apps to register URL schemes. Many apps already use the feature to launch other apps and pass basic data in the URL parameters, but there is no standard for structure of these URLs and no current standard for allowing callbacks to be pass in the URL if the originating app wishes to receive some result based on the action.

The goal of the x-callback-url specification is to provide a standardized means for iOS developers to expose and document the methods they make available to other apps. Using x-callback-url’s source apps can launch other apps passing data and context information, and also provide parameters instructing the target app to return data and control back to the source app after executing an action. Specific supported actions will be dependent on the individual apps and will not be discussed in the specification.

Apps using x-callback-url should provide support for receiving action URLs in the format described below. Details on implementation and sample code will also be available on the x-callback-url website.

Note that starting with iOS 8, Apple has introduced App Extensions which address some of the requirements for inter-app communication in a vendor supported way. There are still areas where URL schemes make more sense, but we recommend using the extension opportunities first.

URL Structure

[scheme]://[host]/[action]?[x-callback parameters]&[action parameters]

scheme

The scheme should be a unique string identifier the target app. URL schemes are registered with iOS via an app’s Info.plist file. To support receiving x-callback-url message, an app must register a protocol with iOS. If your app uses x-callback-url, it is recommend you register a url scheme specifically for x-callback-url support, so that a source app can test for the registration of the scheme and ensure support is present.

host

URLs will be identified by the use of “x-callback-url” as the host portion of the URL.

action

The remaining portion of the URL path after the version make up the name of the action to be executed in the target app. These actions will vary by app and should be documented by the developer of the app supporting x-callback-url.

x-callback Parameters

x-callback-url defines several parameters with specific purposes, all of which are optional. These parameters should be passed as query args in the URL, in the format “key1=value1&key2=value2”. All values should be URL encoded strings.

  • x-source :- The friendly name of the source app calling the action. If the action in the target app requires user interface elements, it may be necessary to identify to the user the app requesting the action.
  • x-success :- If the action in the target method is intended to return a result to the source app, the x-callback parameter should be included and provide a URL to open to return to the source app. On completion of the action, the target app will open this URL, possibly with additional parameters tacked on to return a result to the source app. If x-success is not provided, it is assumed that the user will stay in the target app on successful completion of the action.
  • x-error :- URL to open if the requested action generates an error in the target app. This URL will be open with at least the parameters “errorCode=code&errorMessage=message”. If x-error is not present, and a error occurs, it is assumed the target app will report the failure to the user and remain in the target app.
  • x-cancel :- URL to open if the requested action is cancelled by the user. In the case where the target app offer the user the option to “cancel” the requested action, without a success or error result, this the the URL that should be opened to return the user to the source app.

Action Parameters

In addition to any of the optional parameters defined by x-callback-url, the query arguments can contain action parameters specific to target app’s supported actions. These parameters will be defined by the developer of the app supporting x-callback-url. The “x-” prefix should not be used on action parameters, but be reserved for additional parameters that may be defined by the x-callback-url specification.

Security Concerns

Because URL schemes open pathways to the data stored in your app, it is recommended that you carefully consider security when implementing URL schemes–whether they conform to the x-callback-url specification or not.

How to implement security is not covered by the specification, as the requirements vary greatly for different app, but, in general, URL schemes actions which perform destructive operations, post to services outside the app, or similar “dangerous” actions should require user-confirmation in-app to be sure the user has not unintentionally tapped on a malicious URL. Other mechanisms such as password keys, or similar may make sense for specific use cases.

Learn More

To learn more, check out the Examples and Implementation pages.

x's People

Contributors

extratone avatar

Stargazers

avatar

x's Issues

Original Specification

x-callback-url 1.0 DRAFT Spec

The x-callback-url specification is intended to standardize the use of URLs and registered URL schemes for inter-app communication and messaging on Apple’s iOS platforms.

Revisions

R3: Added “Security Concerns” section.

R2: Added optional “x-cancel” parameter. When supported, this parameter would include a URL to open when the user indicated they want to cancel the action. The action did not succeed, nor generate an error, but the user just wishes to return to the source app.

R1: Removed the “version” from the URL path. The current recommendation if versioning of an x-callback-url API is required would be to register separate URL schemes for each version. This method allows the calling app to determine which versions are available via calls to “canOpenURL”.

Discussion

iOS runs apps in sandboxes which providing limited means of communication between apps directly on the device. Shared files, messaging systems and other similar solutions used on desktop and server operating systems are not present in iOS.

iOS does provide the ability for apps to register URL schemes. Many apps already use the feature to launch other apps and pass basic data in the URL parameters, but there is no standard for structure of these URLs and no current standard for allowing callbacks to be pass in the URL if the originating app wishes to receive some result based on the action.

The goal of the x-callback-url specification is to provide a standardized means for iOS developers to expose and document the methods they make available to other apps. Using x-callback-url’s source apps can launch other apps passing data and context information, and also provide parameters instructing the target app to return data and control back to the source app after executing an action. Specific supported actions will be dependent on the individual apps and will not be discussed in the specification.

Apps using x-callback-url should provide support for receiving action URLs in the format described below. Details on implementation and sample code will also be available on the x-callback-url website.

Note that starting with iOS 8, Apple has introduced App Extensions which address some of the requirements for inter-app communication in a vendor supported way. There are still areas where URL schemes make more sense, but we recommend using the extension opportunities first.

URL Structure

[scheme]://[host]/[action]?[x-callback parameters]&[action parameters]

scheme

The scheme should be a unique string identifier the target app. URL schemes are registered with iOS via an app’s Info.plist file. To support receiving x-callback-url message, an app must register a protocol with iOS. If your app uses x-callback-url, it is recommend you register a url scheme specifically for x-callback-url support, so that a source app can test for the registration of the scheme and ensure support is present.

host

URLs will be identified by the use of “x-callback-url” as the host portion of the URL.

action

The remaining portion of the URL path after the version make up the name of the action to be executed in the target app. These actions will vary by app and should be documented by the developer of the app supporting x-callback-url.

x-callback Parameters

x-callback-url defines several parameters with specific purposes, all of which are optional. These parameters should be passed as query args in the URL, in the format “key1=value1&key2=value2”. All values should be URL encoded strings.

  • x-source :- The friendly name of the source app calling the action. If the action in the target app requires user interface elements, it may be necessary to identify to the user the app requesting the action.
  • x-success :- If the action in the target method is intended to return a result to the source app, the x-callback parameter should be included and provide a URL to open to return to the source app. On completion of the action, the target app will open this URL, possibly with additional parameters tacked on to return a result to the source app. If x-success is not provided, it is assumed that the user will stay in the target app on successful completion of the action.
  • x-error :- URL to open if the requested action generates an error in the target app. This URL will be open with at least the parameters “errorCode=code&errorMessage=message”. If x-error is not present, and a error occurs, it is assumed the target app will report the failure to the user and remain in the target app.
  • x-cancel :- URL to open if the requested action is cancelled by the user. In the case where the target app offer the user the option to “cancel” the requested action, without a success or error result, this the the URL that should be opened to return the user to the source app.

Action Parameters

In addition to any of the optional parameters defined by x-callback-url, the query arguments can contain action parameters specific to target app’s supported actions. These parameters will be defined by the developer of the app supporting x-callback-url. The “x-” prefix should not be used on action parameters, but be reserved for additional parameters that may be defined by the x-callback-url specification.

Security Concerns

Because URL schemes open pathways to the data stored in your app, it is recommended that you carefully consider security when implementing URL schemes–whether they conform to the x-callback-url specification or not.

How to implement security is not covered by the specification, as the requirements vary greatly for different app, but, in general, URL schemes actions which perform destructive operations, post to services outside the app, or similar “dangerous” actions should require user-confirmation in-app to be sure the user has not unintentionally tapped on a malicious URL. Other mechanisms such as password keys, or similar may make sense for specific use cases.

Learn More

To learn more, check out the Examples and Implementation pages.

Google Search Results

"List of apps with x-callback URL" - r/Shortcuts

Thread

JSON

{
  "kind": "Listing",
  "data": {
    "after": null,
    "dist": 1,
    "modhash": "dvoxsr2jxdb5c9912eaa49ee36a1d88bdd3c1ee9816cb8a2e1",
    "geo_filter": "",
    "children": [{
      "kind": "t3",
      "data": {
        "approved_at_utc": null,
        "subreddit": "shortcuts",
        "selftext": "Shortcuts supports x-callback-url, allowing the calling app to receive a response (a callback) when a particular interaction has completed.   \n\n\n* [Shortcuts User Guide](https://support.apple.com/guide/shortcuts/use-x-callback-url-apdcd7f20a6f/ios)\n\nThe x-callback-url spec was written by Greg Pierce, of [Agile Tortoise](http://agiletortoise.com/). \n\n>The goal of the x-callback-url specification is to provide a standardized means for iOS developers to expose and document the methods they make available to other apps. Using x-callback-urlu2019s source apps can launch other apps passing data and context information, and also provide parameters instructing the target app to return data and control back to the source app after executing an action. Specific supported actions will be dependent on the individual apps and will not be discussed in the specification.\n\nThe official [x-callback-url](http://x-callback-url.com/) website introduced a list of (third-party) Apps that support the specification. Throughout the years, several attempts have been made by members of the community to update / document the list of Apps.   \n\n\n* [One Tap Less](https://onetapless.com/library)\n* [AppTalk](https://app-talk.com/)\n* [Opener](https://github.com/timonus/OpenerManifest)\n\nIu2019ve noticed that it can be quite a challenge to find official documentation on the use of x-callback-url for certain iOS Apps. Thatu2019s why I decided to gather all information I could find and list it in an Airtable base. Feel free to use it as a reference (add to homescreen), share around and/or respond with feedback and suggestions.    \n\n\n* [**List of Apps with x-callback-url**](https://airtable.com/shrydOqT26KkIYWnd) (work in progress)  \n\n\n*Inspired by* [*Siri Shortcuts Apps*](https://www.reddit.com/r/shortcuts/comments/axll6p/siri_shortcuts_applications_20_running_list_of/)*, a running list of Apps that supports Siri Shortcuts.(maintained by reddit user* /u/iBanks3)",
        "user_reports": [],
        "saved": false,
        "mod_reason_title": null,
        "gilded": 0,
        "clicked": false,
        "title": "List of Apps with x-callback-url",
        "link_flair_richtext": [{
          "e": "text",
          "t": "Tip/Guide"
        }],
        "subreddit_name_prefixed": "r/shortcuts",
        "hidden": false,
        "pwls": 6,
        "link_flair_css_class": "Tip",
        "downs": 0,
        "thumbnail_height": null,
        "top_awarded_type": null,
        "parent_whitelist_status": "all_ads",
        "hide_score": false,
        "name": "t3_ral96l",
        "quarantine": false,
        "link_flair_text_color": "light",
        "upvote_ratio": 0.98,
        "author_flair_background_color": null,
        "subreddit_type": "public",
        "ups": 72,
        "total_awards_received": 1,
        "media_embed": {},
        "thumbnail_width": null,
        "author_flair_template_id": null,
        "is_original_content": false,
        "author_fullname": "t2_zuh4y",
        "secure_media": null,
        "is_reddit_media_domain": false,
        "is_meta": false,
        "category": null,
        "secure_media_embed": {},
        "link_flair_text": "Tip/Guide",
        "can_mod_post": false,
        "score": 72,
        "approved_by": null,
        "is_created_from_ads_ui": false,
        "author_premium": false,
        "thumbnail": "self",
        "edited": 1639927057.0,
        "author_flair_css_class": null,
        "author_flair_richtext": [],
        "gildings": {},
        "content_categories": null,
        "is_self": true,
        "mod_note": null,
        "created": 1638834429.0,
        "link_flair_type": "richtext",
        "wls": 6,
        "removed_by_category": null,
        "banned_by": null,
        "author_flair_type": "text",
        "domain": "self.shortcuts",
        "allow_live_comments": true,
        "selftext_html": "<!-- SC_OFF --><div class=\"md\"><p>Shortcuts supports x-callback-url, allowing the calling app to receive a response (a callback) when a particular interaction has completed.   </p>\n\n<ul>\n<li><a href=\"https://support.apple.com/guide/shortcuts/use-x-callback-url-apdcd7f20a6f/ios\">Shortcuts User Guide</a></li>\n</ul>\n\n<p>The x-callback-url spec was written by Greg Pierce, of <a href=\"http://agiletortoise.com/\">Agile Tortoise</a>. </p>\n\n<blockquote>\n<p>The goal of the x-callback-url specification is to provide a standardized means for iOS developers to expose and document the methods they make available to other apps. Using x-callback-urlu2019s source apps can launch other apps passing data and context information, and also provide parameters instructing the target app to return data and control back to the source app after executing an action. Specific supported actions will be dependent on the individual apps and will not be discussed in the specification.</p>\n</blockquote>\n\n<p>The official <a href=\"http://x-callback-url.com/\">x-callback-url</a> website introduced a list of (third-party) Apps that support the specification. Throughout the years, several attempts have been made by members of the community to update / document the list of Apps.   </p>\n\n<ul>\n<li><a href=\"https://onetapless.com/library\">One Tap Less</a></li>\n<li><a href=\"https://app-talk.com/\">AppTalk</a></li>\n<li><a href=\"https://github.com/timonus/OpenerManifest\">Opener</a></li>\n</ul>\n\n<p>Iu2019ve noticed that it can be quite a challenge to find official documentation on the use of x-callback-url for certain iOS Apps. Thatu2019s why I decided to gather all information I could find and list it in an Airtable base. Feel free to use it as a reference (add to homescreen), share around and/or respond with feedback and suggestions.    </p>\n\n<ul>\n<li><a href=\"https://airtable.com/shrydOqT26KkIYWnd\"><strong>List of Apps with x-callback-url</strong></a> (work in progress)<br/></li>\n</ul>\n\n<p><em>Inspired by</em> <a href=\"https://www.reddit.com/r/shortcuts/comments/axll6p/siri_shortcuts_applications_20_running_list_of/\"><em>Siri Shortcuts Apps</em></a><em>, a running list of Apps that supports Siri Shortcuts.(maintained by reddit user</em> <a href=\"/u/iBanks3\">/u/iBanks3</a>)</p>\n</div><!-- SC_ON -->",
        "likes": null,
        "suggested_sort": null,
        "banned_at_utc": null,
        "view_count": null,
        "archived": false,
        "no_follow": false,
        "is_crosspostable": true,
        "pinned": false,
        "over_18": false,
        "all_awardings": [{
          "giver_coin_reward": null,
          "subreddit_id": null,
          "is_new": false,
          "days_of_drip_extension": null,
          "coin_price": 125,
          "id": "award_5f123e3d-4f48-42f4-9c11-e98b566d5897",
          "penny_donate": null,
          "coin_reward": 0,
          "icon_url": "https://i.redd.it/award_images/t5_22cerq/5izbv4fn0md41_Wholesome.png",
          "days_of_premium": null,
          "icon_height": 2048,
          "tiers_by_required_awardings": null,
          "resized_icons": [{
            "url": "https://preview.redd.it/award_images/t5_22cerq/5izbv4fn0md41_Wholesome.png?width=16&height=16&auto=webp&s=92932f465d58e4c16b12b6eac4ca07d27e3d11c0",
            "width": 16,
            "height": 16
          }, {
            "url": "https://preview.redd.it/award_images/t5_22cerq/5izbv4fn0md41_Wholesome.png?width=32&height=32&auto=webp&s=d11484a208d68a318bf9d4fcf371171a1cb6a7ef",
            "width": 32,
            "height": 32
          }, {
            "url": "https://preview.redd.it/award_images/t5_22cerq/5izbv4fn0md41_Wholesome.png?width=48&height=48&auto=webp&s=febdf28b6f39f7da7eb1365325b85e0bb49a9f63",
            "width": 48,
            "height": 48
          }, {
            "url": "https://preview.redd.it/award_images/t5_22cerq/5izbv4fn0md41_Wholesome.png?width=64&height=64&auto=webp&s=b4406a2d88bf86fa3dc8a45aacf7e0c7bdccc4fb",
            "width": 64,
            "height": 64
          }, {
            "url": "https://preview.redd.it/award_images/t5_22cerq/5izbv4fn0md41_Wholesome.png?width=128&height=128&auto=webp&s=19555b13e3e196b62eeb9160d1ac1d1b372dcb0b",
            "width": 128,
            "height": 128
          }],
          "icon_width": 2048,
          "static_icon_width": 2048,
          "start_date": null,
          "is_enabled": true,
          "awardings_required_to_grant_benefits": null,
          "description": "When you come across a feel-good thing.",
          "end_date": null,
          "sticky_duration_seconds": null,
          "subreddit_coin_reward": 0,
          "count": 1,
          "static_icon_height": 2048,
          "name": "Wholesome",
          "resized_static_icons": [{
            "url": "https://preview.redd.it/award_images/t5_22cerq/5izbv4fn0md41_Wholesome.png?width=16&height=16&auto=webp&s=92932f465d58e4c16b12b6eac4ca07d27e3d11c0",
            "width": 16,
            "height": 16
          }, {
            "url": "https://preview.redd.it/award_images/t5_22cerq/5izbv4fn0md41_Wholesome.png?width=32&height=32&auto=webp&s=d11484a208d68a318bf9d4fcf371171a1cb6a7ef",
            "width": 32,
            "height": 32
          }, {
            "url": "https://preview.redd.it/award_images/t5_22cerq/5izbv4fn0md41_Wholesome.png?width=48&height=48&auto=webp&s=febdf28b6f39f7da7eb1365325b85e0bb49a9f63",
            "width": 48,
            "height": 48
          }, {
            "url": "https://preview.redd.it/award_images/t5_22cerq/5izbv4fn0md41_Wholesome.png?width=64&height=64&auto=webp&s=b4406a2d88bf86fa3dc8a45aacf7e0c7bdccc4fb",
            "width": 64,
            "height": 64
          }, {
            "url": "https://preview.redd.it/award_images/t5_22cerq/5izbv4fn0md41_Wholesome.png?width=128&height=128&auto=webp&s=19555b13e3e196b62eeb9160d1ac1d1b372dcb0b",
            "width": 128,
            "height": 128
          }],
          "icon_format": null,
          "award_sub_type": "GLOBAL",
          "penny_price": null,
          "award_type": "global",
          "static_icon_url": "https://i.redd.it/award_images/t5_22cerq/5izbv4fn0md41_Wholesome.png"
        }],
        "awarders": [],
        "media_only": false,
        "link_flair_template_id": "13a25ed0-bac1-11e8-940a-0e53f84a3188",
        "can_gild": true,
        "spoiler": false,
        "locked": false,
        "author_flair_text": null,
        "treatment_tags": [],
        "visited": false,
        "removed_by": null,
        "num_reports": null,
        "distinguished": null,
        "subreddit_id": "t5_2s4si",
        "author_is_blocked": false,
        "mod_reason_by": null,
        "removal_reason": null,
        "link_flair_background_color": "#ff66ac",
        "id": "ral96l",
        "is_robot_indexable": true,
        "num_duplicates": 1,
        "report_reasons": null,
        "author": "flashmemories",
        "discussion_type": null,
        "num_comments": 33,
        "send_replies": true,
        "media": null,
        "contest_mode": false,
        "author_patreon_flair": false,
        "author_flair_text_color": null,
        "permalink": "/r/shortcuts/comments/ral96l/list_of_apps_with_xcallbackurl/",
        "whitelist_status": "all_ads",
        "stickied": false,
        "url": "https://www.reddit.com/r/shortcuts/comments/ral96l/list_of_apps_with_xcallbackurl/",
        "subreddit_subscribers": 270025,
        "created_utc": 1638834429.0,
        "num_crossposts": 1,
        "mod_reports": [],
        "is_video": false
      }
    }],
    "before": null
  }
}

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.