beckn deep link and enabling Anchor Tags

[nitinmish]

Context

Beckn is fast catching up as a viable protocol for many transactional oriented systems. While beckn abstracts much of transactional complexities by standardizing specifications and protocol imperatives, it is pertinent that beckn gets identified as an established anchor tag, in line with what upi has done for major platforms (HTML, Android, iOS etc.). A similar tag is available in whatsapp as well. Following are few examples:
upi://pay?pa=upiaddress@okhdfcbank&pn=JohnDoe&cu=INR
whatsapp://send?abid=phonenumber&text=Hello%2C%20World!

Problem

One of the immediate use case for this purpose is enabling QR code for merchant shops. Today, the QR code are either very localized to merchant or have a platform centric approach, where the embedded QR code can only direct to a specific app. There is a need for unbundling this and creating a deep link enabled through anchor tags like that of in upi, that will enable the discovery of store irrespective of the BPP they are associated with. Each BAP shall need to respect a standard anchor tag identified through a beckn complaint application and make the catalog for store visible on device. The anchor tag will also ensure that specific SDKs/Libraries will have an identification of beckn as protocol which developers can use to activate boilerplate codes.

Proposed Solution

We are proposing to have something similar to that of UPI anchor tags, that most platforms for ready references within applications which can be embedded in QR codes. Our use case is that a QR code outside a shop can be pasted that will call a scanner and identify apps that support the URI pushed. I am proposing something similar to below:

beckn://ondc?bppID=&providerID=&providerName=

This will ensure that major software platforms and browsers start recognizing with the protocol beckn. For ONDC, we propose to use the nomenclature above.

The flow of one of the use case is:

1. QR code will scan and input the uri string with beckn as prefix to the scanner.
2. If scanned in a beckn compatible app, the app will extract relevant information and render the page accordingly
3. If scanned in default scanners on devices, the scanners will read and scan for beckn compatible apps and provide a list with options to the user

Examples

• beckn://ondc?bppID=&providerID=&providerName=

References

• UPI github links for UPI example https://github.com/bhar4t/upiqr

@pramodkvarma @ravi-prakash-v @tanya-ondc @BLR-0118 @92shreyansh

[tanya-ondc]

Adding few use cases:

Use Case 1:

The QR code will be available at a seller place like in-store displays, physical advertisements etc. which can be scanned by any buyer willing to look at the catalog. While a QR code is scanned, it will identify the apps that support the URI or are beckn enabled and will return an on_search response with the catalog. The deep link may look like:

beckn://ondc?bppID=<BPP ID>&providerID=<provider ID>&providerName=<name of the store>

Use Case 2:

The beckn enabled deep link can be used in conjunction with voice-based search. When a buyer is looking for coffee using a voice-based search, it can construct the beckn enabled deep link by embedding the recognized keywords into the deep link, which then instructs the OS to identify the apps that support the URI or are beckn enabled and can pass the data embedded in the link to show relevant results in the app.
The deep link may look like:

beckn://ondc?intent=<item/service>&endloc=<gps_coordinates>

Use Case 3:

The beckn enabled deep links can be integrated with advertisements or campaigns to direct users from an add to a beckn enabled application to show relevant results.

[venkatramanm]

Thoughts:

1. Instead of a code for the network (like ondc) , It may be better to embed registry base url. This will enable multiple networks and also allow testing between stage,preprod and prod.
2. Since it is QR codes or links on web , there is no need to have any human-understandable content in the link
3. GPS coordinates of the buyer's location need not be in the url/qr . BAP which processes and parses the link knows the user's GPS information already.
4. Passing more info on the link should be possible for which if we use a scheme that clearly enables bap to construct the search query, it would be good.

Based on these principles, i suggest the following.

For Store QR
beckn://(registry_base_url)?context.bpp_id=${bpp_id}&message.intent.provider.id=${provider_id}
e.g
registry_base_url = pilot-gateway-1.beckn.nsdl.co.in (staging)
registry_base_url = preprod.registry.ondc.org/ondc (preprod)

*. Baps could use (https://${registry_base_url}/lookup} to identify the bpp url and post a /search on the bpp's subscriber url directly,

On an online search if a buy now button is enabled via an ad company such as google , it could be

1. beckn://(registry_base_url)?context.bpp_id=${bpp_id}&message.intent.provider.id=${provider_id}
2. beckn://(registry_base_url)?context.bpp_id=${bpp_id}&message.intent.provider.id=${provider_id}&message.intent.category.id=${category_id}
3. beckn://(registry_base_url)?context.bpp_id=${bpp_id}&message.intent.provider.id=${provider_id}&message.intent.item.id=${item_id}

This pattern can be easily extended if we need to pass more information that is passable in the intent.

@pramodkvarma @ravi-prakash-v

[scaledapps]

Will the same intent be used if there are 2 or more apps on the device, that implement the beckn protocol?

[venkatramanm]

Yes. Even in UPI it is the same. When a UPI intent is presented. , any UPI app can be used to complete the flow.

User gets a choice to select the app .

[tanya-ondc]

Thank you for your comprehensive feedback, @venkatramanm.

I'd like to share a few thoughts on the points you've raised:

Testing between stage, Preprod, and Prod: Current beckn API specifications or protocol doesn't differentiate between environments through parameters, thus not indicating the specific registry endpoint for each. I'm inclined to think that during the testing phase, the QR code should be initially validated with BAPs in the staging and preprod environments. Once validated, BPPs can facilitate its production release. The inclusion of "ondc" will act as an identifier for the intended ONDC registry.

I've also put together a concept note elucidating the QR code use case. I'd appreciate your insights on the same.

To ensure we're aligned and to delve deeper into this topic, will try scheduling a call based on everyone's availability? It could offer us a platform for more streamlined communication and understanding.

[venkatramanm]

Sure @tanya-ondc , let's get on call some time based on availability. As I see ondc will not be the only network. Having code to have mappings to registry etc will make things difficult. Having details in the QR about the network is right but having registry domain seems more versatile. Definitely we can discuss pros and cons in a larger group.

Also the name of parameters to be have prefixing of context. Or message.intent. etc would make it more easy to construct the search json for baps.

[venkatramanm]

The document you shared seemed more like a copy of this thread, you can put my comments from here on that document as feedback if you want to.

I am generally available after 3:30 pm any day incase you are scheduling a call.

[tanya-ondc]

Based on the discussions, have updated the document and added 7 use cases. Please review the document and provide your feedback.

@pramodkvarma @ravi-prakash-v @nitinmish @venkatramanm

[venkatramanm]

1. Can we prefix query parameters with the json path on a search request? That will be more versatile.
   Eg. Context.bpp_id instead of bpp_id, message.intent.* instead of intent.*
2. Beckn is a universal protocol. Having codes for networks like ondc , boc etc. That will then need baps to know the mapping from code to registry.
   Since networks are springing up in other countries and we don't want namespace collisions, it would be better to keep the registry's dns sub domain name.

[ravi-prakash-v]

@tanya-ondc @venkatramanm @nitinmish basis the above discussions, I'd like to summarize the following.

Below is the proposed format.

beckn://<globally unique network identifier>?<path to schema 1>=<value>&<path to schema 2>=<value>&...

For any network, the default network identifier SHOULD be the FQDN. For example, for ONDC, let it be beckn://ondc.org?.... However, it is not necessary to be an FQDN as long as it is globally unique.

The BAP SHOULD maintain an internal lookup table that maps the unique network identifier to the respective registry lookup endpoint of that network. It can be a lookup API, a text file, or anything else that allows the BAP to resolve the network participants of a specific network.

Let us keep the context and message prefixes explicit as it will avoid unnecessary updates to the URI scheme later if more fields get added to the spec.

So an example uri that indicates a search request to browse a specific provider on ONDC can be

beckn://ondc.org?context.action=search&context.version=1.1.0&context.domain=RET10&context.location.city.code=std:011&message.intent.provider.id=12345

This will result in a broadcast search from the BAP

Let's take another case where the provider has availed the services of a search provider (say Google) who has indexed their catalog. In such a case, the bpp_id will be the id of the search provider.

beckn://ondc.org?context.action=search&context.version=1.1.0&context.domain=RET10&context.location.city.code=std:011&context.bpp_id=search.ondc.google.org&message.intent.provider.id=12345

Do provide your thoughts and comments. Thanks

[venkatramanm]

Thanks @ravi-prakash-v

The search provider is also a good point

But not sure though if it would be needed to changed as lookup of the Bpp would be give the search provider any way. That way catalog could be portable across search providers. Any way lets discuss more on the search provider thread.

[tanya-ondc]

Beckn Enabled Deep Links

Objective

To facilitate seamless and standardized user interactions across digital ecosystems, it is crucial to create a universally recognized and standardized "beckn" URI scheme, similar to what Unified Payments Interface (UPI) and WhatsApp has achieved for major platforms like Web, Android and iOS, thus enhancing deep linking capabilities for entities using the Beckn protocol. Furthermore, the scheme should have easy integration and accessibility through software languages like Java, Python, etc.

Problem Statement

Currently, beckn interactions primarily rely on URL-based RESTFul interfaces that are generic and require additional information carried on wire. Moreover, in an unbundled and interoperable framework, there is a need for a standard whereby creation of information datum needs to be standardized creating the possibility of invoking boilerplate codes for specific actions. To enable widespread adoption and interoperability within the ecosystem, there is a need to establish a universally recognized beckn anchor tag that seamlessly integrates with major platforms, similar to UPI, WhatsApp, messaging interfaces (such as XMPP) etc.

For the current use case of enabling QR codes for merchant shops, merchants lack a unified method to generate QR codes, irrespective of the interfaces where the QR will be consumed, which may direct customers to their specific offerings and catalog within the Beckn ecosystem. Even with the QR codes created, the consumers scanning the QR codes might encounter varied landing experiences due to the absence of a standardized deep linking mechanism via anchor tags.

Hence, in order to increase the accessibility and adoption, embedded QR code is required to direct the consumers to apps compliant with beckn. There is a need for unbundling consumer experience, primarily integrated through buyer apps, at the merchant stores. This will also help the merchants to broaden their reach on any network complying to beckn protocol enabling buyers to buy from identified stores of their choice.

Proposed Solution

The solution proposed here is to introduce beckn as an identified anchor tag and established protocol within developer community and platforms such as openJDK, Android, iOS etc. As the first use case, it is proposed to enable QR code features for merchants facilitated by their respective BPPs (Seller Apps in this context).

Creating a QR code with data drafted in a deep link enabled through anchor tags of beckn in line of what UPI/ WhatsApp/XMPP have enabled, will enable the discovery of stores and their catalog on the buyer app of their choice. Consumers shall scan such QR stores visibly available on stores onboarded on any network (like ONDC) through a seller app and will be offered for downloading and displaying in the store. Each BAP shall need to respect a standard anchor tag identified through a beckn complaint application and make the store catalog visible on device. The QR code shall make information available in format below. There are two suggestive modes of operation for this anchor tag, however, buyer Apps are free to innovate and create more handles to provide experience to their buyers.

• the default scanner apps will point to all beckn enabled apps installed on the phone offering buyer a choice to pick one of them.
• The same QR code shall become scannable as an input within App to fetch and render catalog of a specific provider ID as extracted from the URI string mentioned below.

As the primary goal specifically for generating and interpreting QR codes for onboarded merchants, defining the well-defined schema and structure for the beckn anchor tag. This QR code will be available at a seller place like in-store displays, physical advertisements etc. which can be scanned by any buyer willing to engage with a particular seller and their catalog while visiting the store. While a QR code is scanned, it will identify the apps that support the URI or are beckn enabled and will return an on_search response with the catalog.

The deep link for QR code in store is mentioned below:

beckn://<network>?bpp_id=<BPP_ID>&intent.provider.id=<provider_ID>&domain=<domain>&action=<context.action>

Data Fields:

The fields provided here are only for reference and serve as a guidance. As use cases evolve and expand, the input fields in the deep link may also grow or change to cater to the specific needs and scenarios. The field structure refers to the beckn protocol specifications. Below fields are populated based on the use cases defined in below sections.

Fields	Description	Example	Default	Mandatory
bpp_id	Subscriber ID of the BPP	seller-np.com	-	No
bap_id	Subscriber ID of the BAP	buyer-np.com	-	No
version	Version of transaction protocol	1.1.0	-	No
intent.provider.id	Id of the provider/ merchant	P1	-	No
domain	domain code relevant to the catalog	RET10	-	No
action	search, as relevant to searching the catalog.	search	search	No
location.city.code	City code defining the location of buyer and serviceability of seller	std:080	-	No
intent.category.id	Category id within the domain	Foodgrains	-	No
intent.category.descriptor.code	Category code to define the search category	HEALTH_INSURANCE	-	No
intent.fulfillment.stops.type	Type of fulfillment stops	start	-	No
intent.fulfillment.stops.location.gps	Gps location for type of fulfillment stop	28.5566842,77.0980399	-	No
order.provider.items.0.id	Add item to cart	11	-	No

QR code generation

BPPs would facilitate the sellers to generate the QR codes specific to the provider. Networks may offer open-source SDKs designed to produce QR codes embedded with merchant-specific information. However, BPPs may decide to provide their own feature and technology sets to generate standard QR codes with appropriate density for each scanning of the code.

URI scheme Recognition

Each BAP application that are beckn enabled would need to add beckn as the supported URI scheme. When the QR code with deep link - beckn://<network>?bppID=.... is scanned, the system checks for installed applications which can handle the beckn:// scheme.

Platform Integrations

Different platforms have different handling mechanisms, for example, Android uses Intent Filters and iOS uses URL schemes or Universal links to identify which apps can handle which URI schemes or use fallback URLs to redirect the consumer to a fallback web URL, usually prompting them to download the relevant app. If multiple apps have registered the same URI scheme, it will either redirect to the default app or prompt the user to select the app they would like to use.

Network Identification

The component in the deep link identifies the specific network to which the request belongs to. For example,
beckn://<network>?bpp_id=<bpp_id>&intent.provider.id=P1234&domain=RET10&action=search

The BAPs would need to maintain a local lookup table that maps the unique network identifier to the respective registry endpoint based on the network. The registry endpoint may be an API endpoint, a github endpoint, or a local registry DB to lookup the network participants of the specified network.

Interpreting Deep Link

The interpretation of a beckn deep link depends on the specific parameters and values included in the deep link URL. Beckn deep links are designed to convey specific instructions or information to Beckn enabled applications (Buyer Application Platforms or BAPs). Here's a general guide on how a beckn deep link is typically interpreted.

Beckn Deep Link Structure:
beckn://<network>?bpp_id=<BPP_ID>&intent.provider.id=<provider_ID>&domain=<domain>&action=<search>

1. Scheme (beckn://):

   • The custom URI scheme that indicates the deep link is specifically for beckn enabled apps or services.

2. Network ():

   • The component in the deep link identifies the specific network to which the request belongs to. The BAPs would need to maintain a local lookup table to identify the registry endpoint based on the network.

3. Query Parameters:

   • The query parameters are key-value pairs included in the deep link, and they convey specific information for BAP to consume and redirect the user accordingly. All the query parameters are optional.

Defining deep links can help in

1. A standardized schema and structure to QR code generation and interpretation.
2. Consumers are guaranteed a consistent experience regardless of which merchant's QR code they scan.
3. With a standard protocol in place, developers can build and scale faster.
4. Merchants can run targeted campaigns, knowing they can direct users to specific actions or pages seamlessly.

Use Cases:

Deep linking with the beckn URI scheme can open the door to a wide range of use cases, each designed to enhance user interaction, convenience, and efficiency across different domains within the network. While the possibilities are vast, we've cataloged a few illustrative use cases to showcase the potential of this technology.

1. Catalog Access through Seller-Generated QR Codes
   

Imagine a buyer walking into a store and having the power to view the complete merchant's catalog using their smartphone. By scanning a QR code generated by the seller (facilitated by BPP), customers can have instant access to the entire inventory, enhancing the shopping experience while making it more efficient.

Deep Link Structure:
beckn://<network>?bpp_id=sellerapp.com&intent.provider.id=P1&domain=RET10&action=search

When a buyer scans the QR code, the system (buyer’s mobile device) looks for applications that support beckn URI scheme. Once a buyer chooses one specific buyer application (BAP) from the list of applications supported by beckn, the BAP identifies the network and based on the parameters, BAP identifies the action as search, which is the discovery phase and redirects the buyer to the catalog for sellerapp.com.P1 for Grocery (RET10) domain from cache.

The deep link might also look like:
beckn://<network>?bpp_id=sellerapp.com&intent.provider.id=P1

Here default action being search, the buyer will be able to explore the complete catalog irrespective of domains for the specific provider P1 onboarded on bpp - sellerapp.com.

2. Category-Specific Browsing via Seller-Generated QR Codes
   

The seller might want to create QR codes for each category of products, for example Foodgrains in Grocery, which will guide customers to a specific product category, streamlining their search.

Deep Link Structure:
beckn://<network>?bpp_id=sellerapp.com&intent.provider.id=P1&domain=RET10&action=search&intent.category.id=Foodgrains

3. Detailed Product Insight with Seller-Generated QR Codes
   

For products that require a deeper understanding—be it tech gadgets with intricate specifications or luxury goods with detailed craftsmanship—sellers can generate QR codes. Once scanned, these codes will lead customers to a product details page for the specific product.

Deep Link Structure:
beckn://<network>?bpp.id=sellerapp.com&intent.provider.id=P1&domain=RET10&action=search&intent.item.descriptor.name=coffee

4. BAP-Generated QR Codes: A Window to Domain-Specific Catalogs Across BPPs
   

During the festive season, buyer apps (BAPs) might want to generate a QR code for specific domains with some offers. BAPs can generate QR codes that, when scanned, provide users with a consolidated view of offerings from various BPPs within the chosen domain, enriching their browsing experience.

Deep Link Structure:
beckn://<network>?bap.id=buyerapp.com&domain=RET12&action=search

5. Hassle-Free Ride Booking with QR Codes
   

Imagine a QR code present at a public place, like Airport. When a buyer scans the QR code, they are redirected to the buyer app with their current location already set, simplifying their commute process.

Deep Link Structure:
beckn://<network>?bpp.id=mobilitysellerapp.com&domain=TRV10&action=search&intent.fulfillment.stops.type=start&intent.fulfillment.stops.location.gps=28.5566842,77.0980399

6. Explore and buy Health Insurance with QR codes
   

Imagine a buyer comes across a beckn-enabled QR code through an advertisement that promises a hassle-free purchase experience for a health insurance policy.

Deep Link Structure:
beckn://<network>?bpp.id=fis.bpp.com&domain=FIS13&action=search&intent.category.descriptor.code=HEALTH_INSURANCE

7. Directly adding products to cart just by scanning the product QR code
   

Imagine each product in the store has a beckn-enabled QR code associated with it, which links to the product's online listing. The QR code contains a deep link with all the necessary information for adding the product to the cart.

Deep Link Structure:
beckn://<network>?bpp_id=sellerapp.com&order.provider.id=P1&domain=RET14&action=select&order.provider.items.0.id=111

Considerations

1. The merchant generated QR code will have specific bpp id and provider id in the deep link. Hence, a BAP can either:

   • Show the catalog from cache or
   • Send a live search to all BPPs and then show specific merchant’s catalog
   • Send live search for specific bpp id in context, however in that case the BAP would need the bpp url (from local lookup).

2. All BAPs would need to support beckn anchor tags across different platforms i.e. web, android and iOS.

3. The BAPs would need to maintain a local lookup for registry endpoints based on the network, in case the BAP is complying to multiple networks within beckn.

[ravi-prakash-v]

@tanya-ondc do incorporate the suggestions I have made above in the above doc. The data fields section needs change. That is not how we create a URI scheme. Reading this sounds like there are only a limited number of fields allowed in the URI scheme.

[ravi-prakash-v]

Also, keep the language globally relevant. Right now, this document seems more ONDC-specific.

[tanya-ondc]

I recall our conversation about excluding context and message from the request URI in deep links. @ravi-prakash-v

Also, have highlighted in the document that the data fields are examples, serving as guidance and has been populated based on the use cases defined in the document. These may evolve with more use cases. Will add more examples and reference fields for better clarity.

[tanya-ondc]

Also, keep the language globally relevant. Right now, this document seems more ONDC-specific.

I'll revisit the document to ensure its language is universally applicable, catering to any network complying to the beckn protocol, and not just limited to ONDC.

[tanya-ondc]

I have updated the document to make it more generic.

Have added some more example attributes to the data fields table. However, as highlighted in the document, the fields mentioned are only for reference and serve as a guidance. These may evolve and expand to cater to the specific needs and scenarios.
Also, recalling our last conversation, we discussed to exclude the root object, i.e. context and message from the request URI in deep links, to make it more flexible.

@ravi-prakash-v @nitinmish @pramodkvarma

[tanya-ondc]

Updated document based on today's discussion. @ravi-prakash-v Please let me know if it looks good now.

@nitinmish @venkatramanm @pramodkvarma

Beckn Enabled Deep Links

Objective

To facilitate seamless and standardized user interactions across digital ecosystems, it is crucial to create a universally recognized and standardized "beckn" URI scheme, similar to what Unified Payments Interface (UPI) and WhatsApp has achieved for major platforms like Web, Android and iOS, thus enhancing deep linking capabilities for entities using the Beckn protocol. Furthermore, the scheme should have easy integration and accessibility through software languages like Java, Python, etc.

Problem Statement

Currently, beckn interactions primarily rely on URL-based RESTFul interfaces that are generic and require additional information carried on wire. Moreover, in an unbundled and interoperable framework, there is a need for a standard whereby creation of information datum needs to be standardized creating the possibility of invoking boilerplate codes for specific actions. To enable widespread adoption and interoperability within the ecosystem, there is a need to establish a universally recognized beckn anchor tag that seamlessly integrates with major platforms, similar to UPI, WhatsApp, messaging interfaces (such as XMPP) etc.

For the current use case of enabling QR codes for merchant shops, merchants lack a unified method to generate QR codes, irrespective of the interfaces where the QR will be consumed, which may direct customers to their specific offerings and catalog within the Beckn ecosystem. Even with the QR codes created, the consumers scanning the QR codes might encounter varied landing experiences due to the absence of a standardized deep linking mechanism via anchor tags.

Hence, in order to increase the accessibility and adoption, embedded QR code is required to direct the consumers to apps compliant with beckn. There is a need for unbundling consumer experience, primarily integrated through buyer apps, at the merchant stores. This will also help the merchants to broaden their reach on any network complying to beckn protocol enabling buyers to buy from identified stores of their choice.

Proposed Solution

The solution proposed here is to introduce beckn as an identified anchor tag and established protocol within developer community and platforms such as openJDK, Android, iOS etc. As the first use case, it is proposed to enable QR code features for merchants facilitated by their respective BPPs (Seller Apps in this context).

Creating a QR code with data drafted in a deep link enabled through anchor tags of beckn in line of what UPI/ WhatsApp/XMPP have enabled, will enable the discovery of stores and their catalog on the buyer app of their choice. Consumers shall scan such QR codes visibly available on stores onboarded on any network (like ONDC) through a seller app and will be offered for downloading and displaying in the store. Each BAP shall need to respect a standard anchor tag identified through a beckn complaint application and make the store catalog visible on device. The QR code shall make information available in format below. There are two suggestive modes of operation for this anchor tag, however, buyer Apps are free to innovate and create more handles to provide experience to their buyers.

• the default scanner apps will point to all beckn enabled apps installed on the phone offering buyer a choice to pick one of them.
• The same QR code shall become scannable as an input within App to fetch and render catalog of a specific provider ID as extracted from the URI string mentioned below.

As the primary goal specifically for generating and interpreting QR codes for onboarded merchants, defining the well-defined schema and structure for the beckn anchor tag. This QR code will be available at a seller place like in-store displays, physical advertisements etc. which can be scanned by any buyer willing to engage with a particular seller and their catalog while visiting the store. While a QR code is scanned, it will identify the apps that support the URI or are beckn enabled and will return an on_search response with the catalog.

The deep link for QR code in store is mentioned below:

beckn://<network>?context.bpp_id=<BPP_ID>&message.intent.provider.id=<provider_ID>&context.domain=<domain>&context.action=<context.action>&context.version=1.1.0

Data Fields:

The fields provided here are only for reference and serve as a guidance. As use cases evolve and expand, the input fields in the deep link may also grow or change to cater to the specific needs and scenarios. The field structure refers to the beckn protocol specifications. Below fields are populated based on the use cases defined in below sections.

Fields	Description	Example	Default	Mandatory
context.bpp_id	Subscriber ID of the BPP	seller-np.com	-	No
context.bap_id	Subscriber ID of the BAP	buyer-np.com	-	No
context.version	Version of transaction protocol	1.1.0	-	No
message.intent.provider.id	Id of the provider/ merchant	P1	-	No
context.domain	domain code relevant to the catalog	RET10	-	No
context.action	search, as relevant to searching the catalog.	search	search	No
context.location.city.code	City code defining the location of buyer and serviceability of seller	std:080	-	No
message.intent.category.id	Category id within the domain	Foodgrains	-	No
message.intent.category.descriptor.code	Category code to define the search category	HEALTH_INSURANCE	-	No
message.intent.fulfillment.stops.type	Type of fulfillment stops	start	-	No
message.intent.fulfillment.stops.location.gps	Gps location for type of fulfillment stop	28.5566842,77.0980399	-	No
message.order.provider.items.0.id	Add item to cart	11	-	No

QR code generation

BPPs would facilitate the sellers to generate the QR codes specific to the provider. Networks may offer open-source SDKs designed to produce QR codes embedded with merchant-specific information. However, BPPs may decide to provide their own feature and technology sets to generate standard QR codes with appropriate density for each scanning of the code.

URI scheme Recognition

Each BAP application that are beckn enabled would need to add beckn as the supported URI scheme. When the QR code with deep link - beckn://<network>?context.bpp_id=.... is scanned, the system checks for installed applications which can handle the beckn:// scheme.

Platform Integrations

Different platforms have different handling mechanisms, for example, Android uses Intent Filters and iOS uses URL schemes or Universal links to identify which apps can handle which URI schemes or use fallback URLs to redirect the consumer to a fallback web URL, usually prompting them to download the relevant app. If multiple apps have registered the same URI scheme, it will either redirect to the default app or prompt the user to select the app they would like to use.

Network Identification

The component in the deep link identifies the specific network to which the request belongs to. For example,
beckn://<network>?context.bpp_id=<bpp_id>&message.intent.provider.id=P1234&context.domain=RET10&context.action=search

The BAPs would need to maintain a local lookup table that maps the unique network identifier to the respective registry endpoint based on the network. The registry endpoint may be an API endpoint, a github endpoint, or a local registry DB to lookup the network participants of the specified network.

Interpreting Deep Link

The interpretation of a beckn deep link depends on the specific parameters and values included in the deep link URL. Beckn deep links are designed to convey specific instructions or information to Beckn enabled applications (Buyer Application Platforms or BAPs). Here's a general guide on how a beckn deep link is typically interpreted.

Beckn Deep Link Structure:
beckn://<network>?context.bpp_id=<BPP_ID>&message.intent.provider.id=<provider_ID>&context.domain=<domain>&context.action=<search>

1. Scheme (beckn://):

   • The custom URI scheme that indicates the deep link is specifically for beckn enabled apps or services.

2. Network ():

   • The component in the deep link identifies the specific network to which the request belongs to. The BAPs would need to maintain a local lookup table to identify the registry endpoint based on the network.

3. Query Parameters:

   • The query parameters are key-value pairs included in the deep link, and they convey specific information for BAP to consume and redirect the user accordingly. All the query parameters are optional.

Defining deep links can help in

1. A standardized schema and structure to QR code generation and interpretation.
2. Consumers are guaranteed a consistent experience regardless of which merchant's QR code they scan.
3. With a standard protocol in place, developers can build and scale faster.
4. Merchants can run targeted campaigns, knowing they can direct users to specific actions or pages seamlessly.

Use Cases:

Deep linking with the beckn URI scheme can open the door to a wide range of use cases, each designed to enhance user interaction, convenience, and efficiency across different domains within the network. While the possibilities are vast, we've cataloged a few illustrative use cases to showcase the potential of this technology.

1. Catalog Access through Seller-Generated QR Codes
   

Imagine a buyer walking into a store and having the power to view the complete merchant's catalog using their smartphone. By scanning a QR code generated by the seller (facilitated by BPP), customers can have instant access to the entire inventory, enhancing the shopping experience while making it more efficient.

Deep Link Structure:
beckn://<network>?context.bpp_id=sellerapp.com&message.intent.provider.id=P1&context.domain=RET10&context.action=search

When a buyer scans the QR code, the system (buyer’s mobile device) looks for applications that support beckn URI scheme. Once a buyer chooses one specific buyer application (BAP) from the list of applications supported by beckn, the BAP identifies the network and based on the parameters, BAP identifies the action as search, which is the discovery phase and redirects the buyer to the catalog for sellerapp.com.P1 for Grocery (RET10) domain from cache.

The deep link might also look like:
beckn://<network>?context.bpp_id=sellerapp.com&message.intent.provider.id=P1

Here default action being search, the buyer will be able to explore the complete catalog irrespective of domains for the specific provider P1 onboarded on bpp - sellerapp.com.

2. Category-Specific Browsing via Seller-Generated QR Codes
   

The seller might want to create QR codes for each category of products, for example Foodgrains in Grocery, which will guide customers to a specific product category, streamlining their search.

Deep Link Structure:
beckn://<network>?context.bpp_id=sellerapp.com&message.intent.provider.id=P1&context.domain=RET10&context.action=search&message.intent.category.id=Foodgrains

3. Detailed Product Insight with Seller-Generated QR Codes
   

For products that require a deeper understanding—be it tech gadgets with intricate specifications or luxury goods with detailed craftsmanship—sellers can generate QR codes. Once scanned, these codes will lead customers to a product details page for the specific product.

Deep Link Structure:
beckn://<network>?context.bpp.id=sellerapp.com&message.intent.provider.id=P1&context.domain=RET10&context.action=search&message.intent.item.descriptor.name=coffee

4. BAP-Generated QR Codes: A Window to Domain-Specific Catalogs Across BPPs
   

During the festive season, buyer apps (BAPs) might want to generate a QR code for specific domains with some offers. BAPs can generate QR codes that, when scanned, provide users with a consolidated view of offerings from various BPPs within the chosen domain, enriching their browsing experience.

Deep Link Structure:
beckn://<network>?context.bap.id=buyerapp.com&context.domain=RET12&context.action=search

5. Hassle-Free Ride Booking with QR Codes
   

Imagine a QR code present at a public place, like Airport. When a buyer scans the QR code, they are redirected to the buyer app with their current location already set, simplifying their commute process.

Deep Link Structure:
beckn://<network>?context.bpp.id=mobilitysellerapp.com&context.domain=TRV10&context.action=search&message.intent.fulfillment.stops.type=start&message.intent.fulfillment.stops.location.gps=28.5566842,77.0980399

6. Explore and buy Health Insurance with QR codes
   

Imagine a buyer comes across a beckn-enabled QR code through an advertisement that promises a hassle-free purchase experience for a health insurance policy.

Deep Link Structure:
beckn://<network>?context.bpp.id=fis.bpp.com&context.domain=FIS13&context.action=search&message.intent.category.descriptor.code=HEALTH_INSURANCE

7. Directly adding products to cart just by scanning the product QR code
   

Imagine each product in the store has a beckn-enabled QR code associated with it, which links to the product's online listing. The QR code contains a deep link with all the necessary information for adding the product to the cart.

Deep Link Structure:
beckn://<network>?context.bpp_id=sellerapp.com&message.order.provider.id=P1&context.domain=RET14&context.action=select&message.order.provider.items.0.id=111

Considerations

1. The merchant generated QR code will have specific bpp id and provider id in the deep link. Hence, a BAP can either:

   • Show the catalog from cache or
   • Send a live search to all BPPs and then show specific merchant’s catalog
   • Send live search for specific bpp id in context, however in that case the BAP would need the bpp url (from local lookup).

2. All BAPs would need to support beckn anchor tags across different platforms i.e. web, android and iOS.

3. The BAPs would need to maintain a local lookup for registry endpoints based on the network, in case the BAP is complying to multiple networks within beckn.

[nitinmish]

I believe we have specs that are good to start with. Let's enable the first use case of creation of QR code by sellers to help buyers explore their catalog while in store. Future use cases and their model implementations will evolve as we foray into its assimilation in the eco-system.

@ravi-prakash-v , Do we need to checkin a PR for these specs under protocol specifications? Please advise.

@venkatramanm @BLR-0118 @tanya-ondc @pramodkvarma