Proposal: Add deep links for iOS, Android, and web apps

[barbeau]

Applications consuming GBFS would like to show markers for the available bikes and stations on the map, and when the user taps on these show a link that they can follow to rent that particular bike (for free bikes) or a bike at that particular station (for station-based systems).

Currently, to implement this feature rental URLs need to be hard-coded in the application for each bike/share vendor/deployment.

This patch proposes the capability to discover these rental_urls directly from the GBFS feed for each free bike and station. It's intended to be a starting point for discussion, so comments/improvements are welcome.

We've implemented the rental link via the proprietary hard-coded approach mentioned above at https://maps.usf.edu/#layers/bike_stations for the SoBi deployment at USF:

If SoBi is willing to prototype this field in their GBFS feed for the USF deployment we'd be willing to try it out in the above application (based on OpenTripPlanner).

cc @fruminator @jmfield2

[barbeau]

cc @fpurcell

[fpurcell]

+1

We plan to add BIKETOWN bike and rack locations to the TriMet map (http://ride.trimet.org) later this summer. Without Sean's additions to the spec (and implementation on the BIKETOWN reservation app), the customer will find a bike or rack on the TriMet map, and then they'd have to again find that bike or rack on the BIKETOWN vendor page. So having some simple linkage integration between sites (ala what Sean and SoBi have done) will be very helpful.

[jcn]

I would like to codify this a little more as per #3 but my feeling is that before rolling out an actual change to the spec, you should work with SoBi to implement this in their own feeds and work out any of the issues that might arise in the production use of this kind of feature. Once you've ironed those out, you can submit a PR (or change this from a WIP to a proposal) and we can hash out the details among the other vendors.

@barbeau For example, one problem in my mind with the current proposed spec is that it relies on both a fully qualified url AND a parameter with a fixed name (station_id or bike_id). We might be able to do something with variable substitutions in the spec, URL, but that seems messy. By trying this out in the real world (maybe among a couple of different SoBi systems) you will hopefully hit on something that works generically and handles all the cases that we might not even be thinking of yet.

[cubbi]

SoBi has a different deep linking API available for both mobile and web apps that works across the systems, I am not sure if there is a need to implement a custom field for those urls in GBFS, however I am open to discuss that. If you would like to learn more about those API's please send us email at [email protected] and I will send you back the spec.

[barbeau]

One problem in my mind with the current proposed spec is that it relies on both a fully qualified url AND a parameter with a fixed name (station_id or bike_id).

@jcn I'm not sure I understand why this would be a problem - could you please elaborate?

I am not sure if there is a need to implement a custom field for those urls in GBFS, however I am open to discuss that

@cubbi Without having a deep linking URL discoverable via GBFS, how else would an application know what URL to use to direct a user to rent a particular floating bike or bike at a particular hub?

please send us email at [email protected] and I will send you back the spec.

Thanks! Just sent you an email.

[barbeau]

@cubbi Still haven't heard back from [email protected] request. Would you be able to look at this?

[jcn]

One problem in my mind with the current proposed spec is that it relies on both a fully qualified url AND a parameter with a fixed name (station_id or bike_id).

@barbeau The spec shouldn't force the implementer to have to conform to a particular url scheme. What I would suggest is the following:

• For dock-based systems, purchase_url should just be a full URL for purchasing for a particular station, it should be the complete URL and it should be included in station_information instead of station_status
• For the free_bike_status feed, again, the purchase_url should be the full URL that the client should hit to purchase a pass at that bike - no string building needed at all

This ends up being redundant, but it removes from the client the need to have to build URLs themselves.

[barbeau]

• For dock-based systems, purchase_url should just be a full URL for purchasing for a particular station, it should be the complete URL and it should be included in station_information instead of station_status
• For the free_bike_status feed, again, the purchase_url should be the full URL that the client should hit to purchase a pass at that bike - no string building needed at all

That works for me - simpler for the client, and off the top of my head I can't think of any reason why this wouldn't work. I just force-pushed a new commit into this PR with those changes. I believe we should specify that these URLs should be pre-encoded by the GBFS provider as well, so the client can assume that the URL would work as-is (to avoid double-encoding). I've added text for that as well. Also added the "deep link" term and clarified that URLs should direct to a single bike/station rental context.

[jcn]

@barbeau No need to force-push anything - just push a new commit. That way it's clear what the original proposal was and what it was changed to. We can squash the commit when we merge if necessary.

That said, I would still stand by my original suggestion that you work with a vendor to provide this data first and see whether or not it works right, before we merge it into the spec. Real-world usage data beats theory any day, and it's sure to uncover weirdness.

[barbeau]

@jcn Through the magic of Git, both commits are now back in this PR :).

That said, I would still stand by my original suggestion that you work with a vendor to provide this data first and see whether or not it works right, before we merge it into the spec. Real-world usage data beats theory any day, and it's sure to uncover weirdness.

I agree 100%, we're willing to do this. Hopefully SoBi will be willing to add the fields to the Share-A-Bull GBFS feed.

[fruminator]

@cubbi we've been asked about the state of this conversation for Portland. I agree with @jcn that we should try it first with vendor extensions (e.g. sobi_purchase_url) and see if it works in situ in south florida. once you and @barbeau get it working we can talk about folding it into the spec proper.

[barbeau]

@fruminator Unfortunately from a conversation between @cubbi and I offline, SoBi does not want to proceed with testing this field as part of their GBFS feed. We are obviously disappointed, as we see this feature as being a key integration point between GBFS consumers and producers, and one that significantly improves the UX. @cubbi can elaborate on SoBi's rationale here if he'd like.

[barbeau]

Would any other vendor be willing to implement these fields in their GBFS feed?

We will likely be working on systems in other cities in the near future and I'd like to try and get a proof-of-concept going sooner rather than later.

[fruminator]

@cubbi can you please explain the rationale? for broader context, TriMet in Portland, OR also uses Open Trip Planner and wants to work with @barbeau to get this functionality into that open source project broadly, so the work would be immediately applicable in Portland as well as Florida. I think there is also an LA-area implementation of OTP as well.

Thanks
Mike

[cubbi]

@fruminator We have a different, way more complex deep linking API and entire functionality can not be implemented in one field - "purchase_url". We are right now testing it with few app developers and hope to release documentation later this year. Also I personally think it's such a vendor specific feature, that it might not make sense in a feed like GBFS.

[jcn]

@cubbi I feel like a file spec like GBFS is exactly where this kind of logic would go. By providing a standard mechanism for consumer applications to be able to add purchasing linking, it means that they're able to build their applications more generically across multiple cities.

By not implementing direct-purchasing URLs in the standard (for systems where it makes sense) it means that every application developer is going to need to implement specific logic for every system/city they implement, which is exactly the problem that GBFS was aiming to avoid.

[nackko]

I second that opinion : that's why even at the raw data level we have
citybik.es which was the best thing ever invented for bike sharing app
developers.
Payment must be integrated in a standard way, and GBFS is the perfect place
for that.

[cubbi]

It's not about payment link. The original request was about deep linking to the app - to book individual bicycle from station or one from selected station. We (SoBi) offer deep linking on web level or mobile app level (using custom schema). In our case, we would have to implement at least two different urls, because we do not know if you are consuming feed as mobile app or web, and we offer a lot of different options in deep linking URL to manage behaviour once user will rent bicycle. There is no place for that in current GBFS feed. We offer a GBFS link for signup which we publish inline with the GBFS spec.

[nackko]

Ok, I'm following conversations here loosely because I develop a multi city
app.
I understand soBi is far advanced. But specificity IS a problem, and GBFS
should tend to fix it, no matter if an individual vendor already has a non
fitting solution, in my opinion.

[barbeau]

We (SoBi) offer deep linking on web level or mobile app level (using custom schema). In our case, we would have to implement at least two different urls, because we do not know if you are consuming feed as mobile app or web

@cubbi This isn't correct - this can be implemented with a single URL across desktop/mobile web, iOS, and Android, and therefore with a single field in GBFS.

I would suggest that we require the http:// scheme in the purchase_url fields I'm proposing here. On desktop, this just simply works. On mobile, when a user taps on this URL on a web page in a mobile web browser, by default they will be opened in the mobile browser. If the vendor chooses, you can support deep linking to your native Android and iOS apps using the same http:// scheme - here's an example on Android, and here's an example on iOS. So, when the user taps on the link in the browser, they'd be directed to the screen in the native app to rent that bike.

If anyone else has any suggestions for improving this, please let me know.

[fruminator]

if @barbeau is right then it seems really straightforward. if not, at worst we could have 2 fields: purchase_url and mobile_purchase_url (both of which would be optional) or something along those lines.

[barbeau]

@cubbi given your current spec as I understand it, you could populate the purchase_url with the http scheme you currently support - for example http://app.socialbicycles.com/map?bike_id=3516. This is the format we're currently hard-coding on https://maps.usf.edu.

[barbeau]

Wondering if ad_id and token parameters should be removed for now since their usage is underspecified.

I agree that if no one is going to implement this in the initial producers/consumer implementations then we should remove it.

Could anyone implementing share if they play to implement this feature?

[madupras]

+1 from PBSC

[hbruch]

+1 from MFDZ

[barbeau]

According to the governance pilot proposal here, we need at least one producer and consumer to commit to implementing a proposal prior to acceptance.

BCycle has committed to implementing as a producer in their vote.

@kanagy @MuteQ @evansiroky (and any other consumers I missed) Can you commit to implementing this deep links proposal as a consumer?

[MuteQ]

Transit will implement the deep link proposal as a consumer

[hbruch]

MFDZ will implement the web-URI consumer in it‘s OpenTripPlanner / Digitransit-UI fork. We expect to have https://www.leihleeze.de/ as producer.

[johnpena]

Agree with this comment from @kanagy :

Wondering if ad_id and token parameters should be removed for now since their usage is underspecified.

Otherwise, +1 from Lime as a producer

[quicklywilliam]

+1 Ride Report

[rowillia]

Lyft has some concerns with the "First Click Free" language - this would require some major re-architecture of our apps (I'm sure other providers would have similar issues) and isn't a super common scenario. This is currently marked as "should" - we will not be requiring providers to do this, correct?

For what it's worth Google has since moved away from requiring FCF.

[rowillia]

+1 from Lyft (assuming #25 (comment) is optional)

[charlesjump]

+1 JUMP (same sentiment with Lyft's comment on "First Click Free")

[barbeau]

The vote on this deep links proposal is now closed.

Votes for:

1. Stae
2. IBI Group
3. TriMet
4. Google Maps
5. BCycle - Committed producer
6. PBSC
7. MFDZ - Committed consumer
8. Transit - Committed consumer
9. Lime - Committed producer
10. Ride Report
11. Lyft
12. JUMP

No votes against.

So it passes! And we also have 2 committed producers and 2 committed consumers! 🎉

@rowillia @charlesjump The contents of the page at the "first click free" link has changed since I originally wrote the proposal, so to avoid re-voting on this I've made the executive decision to remove the following sentence from this proposal:

This is the same principle as the "first click free" experience for web sites.

This sentence was only intended to reinforce the concepts discussed in the previous sentences, so removing it doesn't change the intent or requirements of the proposal. And yes, a previous sentence is The deep link should take users directly to this station, without any prompts, interstitial pages, or logins, so it does allow for exceptions.

If anyone who voted disagrees with removing this sentence please let me know and we can re-open the vote.

Following the goverance pilot process outlined here, here are the next steps:

1. I'll update these proposed deep link fields with the (beta) label and merge this proposal.
2. After they are implemented, the (beta) label will be removed and the feature will be tagged as part of an official release.

Wondering if ad_id and token parameters should be removed for now since their usage is underspecified.

@kanagy @johnpena if no one implements these parameters, the (beta) label won't be removed and they won't be part of the official release.

[mdwestervelt]

I know we've missed the voting period, but from Bird's perspective we're not able to implement at this time without the requirement of a login.

[sven4all]

What do you mean without the requirement of a login? A deeplink is always to an (web/ios/android) application owned by the operator. So I guess that for alle operators being logged in in that application is a requirement.

[heidiguenin]

We'd love to make this an official part of the spec, but first we need to see this change being implemented. Could you comment here if your organization is producing or consuming deeplinks?

@hbruch @lindarand @MuteQ @johnpena committed to implementing earlier - has that happened yet? Others?

[MuteQ]

Transit would be consuming the deeplink info. I'm unaware of any public feed that currently implements this spec. If I'm mistaken, let me know and Transit will gladly consume the new data. We would also love for the deeplink info to become an official part of the spec.

[fpurcell]

I'm using an unpublished link parameter that exists on the Sobi website to go from individual bikeshare hubs on this map https://ride.trimet.org/?tool=bikeshare over to that same hub on the BIKETOWN/Sobi site, ala https://app.socialbicycles.com/map?hub_id=1600

It would be a big improvement (and I'd work to get it implemented in OpenTripPlanner) to have such urls published via the gbfs spec.

[MFazio23]

BCycle has implemented these changes and they are publicly available. This includes the rental apps section for the systems and rental URIs for stations/free bikes.

Using Metro Bike Share as an example

• System Information: https://gbfs.bcycle.com/bcycle_lametro/system_information.json
• Station Information: https://gbfs.bcycle.com/bcycle_lametro/station_information.json
• Free Bikes: https://gbfs.bcycle.com/bcycle_lametro/free_bike_status.json

[kanagy]

Google Maps implemented free_bike_status.rental_uris to support deep links from Lime.

[MuteQ]

Ah, didn't know about BCycle. That's great. We'll add support to consume the new rental data. Should be done by next week.