| Note |
|---|
This is a template that should be used to document each feature. It’s meant to be easy, not prescriptive - change it at will! |
Table of contents
| Table of Contents |
|---|
Definition
Status
| Status | ||||
|---|---|---|---|---|
|
RBIberia Owner
RBI Owner
❓ Open questions
| Info |
|---|
We need to constantly make this section empty. |
Requirements
Problem statement
The white-label application lacks a corresponding flow to purchase additional ketchup, similar to the existing implementation in the AirTouch application.
The current process in AirTouch allows users to acquire extra ketchup beyond the free quantity specified in the Sanity configuration for each product. Users are required to pay for this additional ketchup if desired.
Furthermore, at the moment of adding the first product with ketchup to the cart, the application shows a screen that informs users about the "King Planet" initiative.
Following, the screenshots showing how it works on the Airtouch application:
How the feature work today:
After inserting the first hot product into the cart:
Card on the cart screen to add the extra ketchup:
Card to increase the number of ketchup packet and the info message:
Acceptance criteria
Sanity
The configuration of the link between products and the quantity of ketchup should be accurately set up and managed within the Sanity CRM system.
Don´t have limitation of quantity of ketchup.
Users should have the option to acquire extra ketchups beyond the free quantity specified in the Sanity configuration for each product.
The Ketchup configuration should include necessary details such as name, price, and availability.
Any changes or updates to the ketchup product should be done by the Sanity application.
White-label
King planet
The white-label application's functionality for purchasing additional ketchups and displaying the "King Planet" initiative screen should include a feature toggle.
The feature toggle should allow enabling or disabling the functionality at runtime without requiring code changes or deployments.
Disabling the feature toggle should disable the additional ketchup purchase flow and hide the "King Planet" initiative screen, ensuring they are not accessible to users.
Enabling the feature toggle should make the additional ketchup purchase flow and "King Planet" initiative screen accessible and visible to users.
The white-label application should introduce a flow that enables users to purchase additional ketchup, resembling the existing implementation in the AirTouch application.
The white-label application should incorporate a screen that informs users about the "King Planet" initiative the moment they add the first product with ketchup to their cart.
The "King Planet" initiative screen should provide a clear and concise description as described on the figma design.
The inclusion of the "King Planet" initiative screen should not disrupt the overall flow of adding products to the cart and completing the checkout process.
The white-label appear only in the first access in each order when the order already have some product with free ketchup available.
The white-label allows to add 1 free ketchup in the order.
Purchase flow
On the cart screen of the white-label application, a dedicated section should be available to display the ketchup and its corresponding cost.
Within this section, users should have the option to add the ketchup to their cart for purchase.
The cart screen should provide a clear overview of the total cost of the ketchup added, taking into account the quantity and individual prices.
Once the user has finished adding ketchups to the cart, the flow to complete the order should follow the same process as the current implementation.
Users should be able to edit the quantity of the ketchup they wish to buy, and the cost should update accordingly to reflect the changes.
Users should have the option to acquire extra ketchup beyond the free quantity for each product specified in the Sanity configuration.
The white-label application should accurately reflect the product configurations in Sanity, including the number of free ketchups and any associated pricing for additional ketchups.
The purchasing flow for additional ketchups should be integrated with existent purchase flow.
The white-label application should calculate and display the cost of additional ketchups when users choose to purchase them.
Users should be prompted to pay for the additional ketchups during the checkout process, ensuring a smooth and transparent transaction.
The additional ketchup purchase flow and the "King Planet" initiative screen should to ensure proper responsiveness and usability.
Documentation should be provided, detailing the implementation and configuration of the additional ketchup purchase flow and the "King Planet" initiative screen in the white-label application.
In the cart there is an automatic rule to move the paid ketchup to the free ketchup when the customer adds more items with free ketchup available
When the customer removes products that reduce their amount of free ketchup, then in the cart there is an automatic rule to remove paid ketchups and free ketchups greater than the amount available. This rule is only applied when the customer has more than the free ketchup available at the time.
There is no quantity limitation to add any quantity of the same product to the cart.
Solution
The main idea of the solution was to reuse the existing /wiki/spaces/FE/pages/3497590902 feature and make something not tied only to the Ketchup idea. Our solution will able to the client offer any item to the user.
We also use the Addon Extras feature in the Bag With Handles solution. The Addon extras feature will solve for us the following:
A modal that will hold all the extras items
The edit of the extra item
The re-order behavior (not letting the client open a re-order with an extra added directly)
All the flow for the order, receipt, and so on, is already done
Requirements to work
We need to turn ON the following feature flags:
Launchdarkly: intl-guest-app
enable-add-on-as-cart-itemenable-free-addon-on-cartoptional:
enable-add-extras(if we want to show the “+ Add extras” button in the “Your Cart” section)
For this solution to work, we need to ensure that Sanity is properly configured:
The creation of the desired Add On Section
The sections here can be created and saved to be used later because they need to be added to the feature menu.
Add the Add On Sections that we want to show in the cart into Feature Menu
The order of the list defines the order that the sections will be shown on the cart checkout page.
Configure the Add On Section correctly to have the behavior to deal with free items:
“Show as a separate section on cart” (ON)
“Make options in this section as free add-ons” (ON)
“Service Modes”
Here we’ll choose the desirable service modes that we want to offer the promotion
Configure the options (addons) for this Add On Section
Add the paid item (“Option”)
Add the free item (“Free Option”)
Important: the free item needs a PLU with zero price to have the correct behavior
In the “Vendor Configs”
“PLU Type” = “Constantplu”
“Constant PLU” field = “zero PLU”
Obs: for development, we can use the “PLU Type” as ignore, and the product will have zero as the value
Configure the “Menu options that Offer the Free Options Above”
Here we’ll configure the item that will receive the offer and the maximum free items quantity
We can select between “Item” or “Combo” in the list
Example of the “Combo” use case:
In Sanity the items that have an offer are:
1 free item offer for the “Menu 2 pieces regular for 1”
1 free item offer for the “8 Onion Rings”
With that, I’ll have 2 free items available for this cart configuration:
This can be very dynamic (examples):
If we have only the “8 Onion Rings” in the cart for example we’ll have only 1 offer instead
If I remove the combo from the Sanity offer I’ll have only 1 offer for the “8 Onion Rings” that exist inside the Combo
The main idea is: “Do we have an item inside the combo/item that has some offer?” → If yes this will be counted in the offer amount
Configure the “Free Add On Modal” fieldset if wants to show the promotional modal when the user enters the checkout page
The fieldset “Free Add On Modal” will be available for all options in the “Add On Section” and with that, we’ll have one modal for each free item (option)
“Show Free Add-On Modal at Checkout” → if ON we’ll have this modal shown in the cart
This toggle is very useful. If you don’t want an specific modal to be shown, just turn the toggle OFF
The image and description are optional. Title and CTA are required if the toggle is ON.
If none image is selected the modal will show as a fallback the free item image
If some image is selected this image will be shown
To avoid quantity limits for the added items in the cart we need to configure the following on Sanity:
In the example above the user can select only 20 items (individually) in the cart.
This limit will also affect the addons items. Even if we offer 30 free items the user cannot select more than 20 items (in this example).
Front-end behaviors and Business rules
After all the requirements are configured, we’ll have the following things on the FE UI:
Promotional modal when entering the checkout the first time/journey/order
Basic Rules
Show the modal only for the first time (and always if we have a “new cart”, eg: cleaning the cart and adding the products again)
If the user hits F5 the modals already saw will not be shown on the screen, only the new ones
If we have only one modal ON we’ll not show the modal in the carousel format/approach
For more details of carousel buttons behavior: https://rbictg.atlassian.net/wiki/spaces/IBC/pages/4169040346/Whitelabel+Add+free+extras+modal+on+checkout+page+cart#Task-2%3A-Add-carousel-logic-in-modal-content
The modal will show content for every section that has a matching item (the configured option inside the Add On Section) with an offer on the cart
Checkout sections
In this example, I have the “Add Ketchup” and “Add Sauces” sections. Some rules for this part of the screen
If the user did not add the free items through the promotional modal he’ll see the free offers on the screen
If click on the free item:
Is the maximum of free items selected in the cart?
Yes - show the paid item in the section
No - hide the section from the screen if the section doens’t have other items to offer
We’ll only show the section if at least one item from the section has an offer
We’ll show only items that have an offer in the section (individually)
Your Cart behavior with free/paid items
The free item will have a description about the maximum of the free items available with the items combined in the cart:
Quantity of the item that offers the free item X sanity free quantity → In this example “The Sandwich” offers 1 free item, so: 1 x 1 = the maximum for Ketchup free is 1
The free item will have 0.00 for the price (will not use any label here because we want to ensure the same consistency between receipt and front-end)
Automatic “balance” of the cart content based on the following rules:
The user cannot pay for an item if he has free items available to select
The user cannot buy additional free items (besides what's been offered)
The app will remove/add free and paid as needed to balance the original quantity on the cart
Remove free and paid items from the cart if the main item (that holds the offer) is removed
Extras modal to edit addons
The user will edit the quantity for the addons by clicking on the “Edit” button that will open the “Add extras” modal
The modal will also respect the rules for maximum free items → In this example the user can select a maximum of 1 Free item and he’ll be able to select the paid item if want more add-ons
The paid item will only be offered if the free is on maximum during the edition in this modal
The edition in this modal doens’t changes the cart in the background. The edition will be made only after clicking on the “Update Order” button
Troubleshoot
Section with free items is not in the checkout?
All the flags and toggles should be ON as showed in the Requirements section
Sanity needs to be configured properly and the right item (that is offering the free ones) needs to be in the cart
If some item used as a free/paid addon in the Add On Section options has an invalid configuration the entire section will be invalid (for example an invalid PLU, or invalid item config, which will be checked on POS)
| Note |
|---|
This is a template that should be used to document each feature. It’s meant to be easy, not prescriptive - change it at will! |
Table of contents
| Table of Contents |
|---|
Definition
Status |
| ||||||
RBIberia Owner | |||||||
RBI Owner |
❓ Open questions
| Info |
|---|
We need to constantly make this section empty. |
Requirements
Problem statement
The white-label application lacks a corresponding flow to purchase additional ketchup, similar to the existing implementation in the AirTouch application.
The current process in AirTouch allows users to acquire extra ketchup beyond the free quantity specified in the Sanity configuration for each product. Users are required to pay for this additional ketchup if desired.
Furthermore, at the moment of adding the first product with ketchup to the cart, the application shows a screen that informs users about the "King Planet" initiative.
Following, the screenshots showing how it works on the Airtouch application:
How the feature work today:
After inserting the first hot product into the cart:
Card on the cart screen to add the extra ketchup:
Card to increase the number of ketchup packet and the info message:
Acceptance criteria
Sanity
The configuration of the link between products and the quantity of ketchup should be accurately set up and managed within the Sanity CRM system.
Don´t have limitation of quantity of ketchup.
Users should have the option to acquire extra ketchups beyond the free quantity specified in the Sanity configuration for each product.
The Ketchup configuration should include necessary details such as name, price, and availability.
Any changes or updates to the ketchup product should be done by the Sanity application.
White-label
King planet
The white-label application's functionality for purchasing additional ketchups and displaying the "King Planet" initiative screen should include a feature toggle.
The feature toggle should allow enabling or disabling the functionality at runtime without requiring code changes or deployments.
Disabling the feature toggle should disable the additional ketchup purchase flow and hide the "King Planet" initiative screen, ensuring they are not accessible to users.
Enabling the feature toggle should make the additional ketchup purchase flow and "King Planet" initiative screen accessible and visible to users.
The white-label application should introduce a flow that enables users to purchase additional ketchup, resembling the existing implementation in the AirTouch application.
The white-label application should incorporate a screen that informs users about the "King Planet" initiative the moment they add the first product with ketchup to their cart.
The "King Planet" initiative screen should provide a clear and concise description as described on the figma design.
The inclusion of the "King Planet" initiative screen should not disrupt the overall flow of adding products to the cart and completing the checkout process.
The white-label appear only in the first access in each order when the order already have some product with free ketchup available.
The white-label allows to add 1 free ketchup in the order.
Purchase flow
On the cart screen of the white-label application, a dedicated section should be available to display the ketchup and its corresponding cost.
Within this section, users should have the option to add the ketchup to their cart for purchase.
The cart screen should provide a clear overview of the total cost of the ketchup added, taking into account the quantity and individual prices.
Once the user has finished adding ketchups to the cart, the flow to complete the order should follow the same process as the current implementation.
Users should be able to edit the quantity of the ketchup they wish to buy, and the cost should update accordingly to reflect the changes.
Users should have the option to acquire extra ketchup beyond the free quantity for each product specified in the Sanity configuration.
The white-label application should accurately reflect the product configurations in Sanity, including the number of free ketchups and any associated pricing for additional ketchups.
The purchasing flow for additional ketchups should be integrated with existent purchase flow.
The white-label application should calculate and display the cost of additional ketchups when users choose to purchase them.
Users should be prompted to pay for the additional ketchups during the checkout process, ensuring a smooth and transparent transaction.
The additional ketchup purchase flow and the "King Planet" initiative screen should to ensure proper responsiveness and usability.
Documentation should be provided, detailing the implementation and configuration of the additional ketchup purchase flow and the "King Planet" initiative screen in the white-label application.
In the cart there is an automatic rule to move the paid ketchup to the free ketchup when the customer adds more items with free ketchup available
When the customer removes products that reduce their amount of free ketchup, then in the cart there is an automatic rule to remove paid ketchups and free ketchups greater than the amount available. This rule is only applied when the customer has more than the free ketchup available at the time.
There is no quantity limitation to add any quantity of the same product to the cart.
Solution
The main idea of the solution was to reuse the existing /wiki/spaces/FE/pages/3497590902 feature and make something not tied only to the Ketchup idea. Our solution will able to the client offer any item to the user.
We also use the Addon Extras feature in the Bag With Handles solution. The Addon extras feature will solve for us the following:
A modal that will hold all the extras items
The edit of the extra item
The re-order behavior (not letting the client open a re-order with an extra added directly)
All the flow for the order, receipt, and so on, is already done
Requirements to work
We need to turn ON the following feature flags:
Launchdarkly: intl-guest-app
enable-add-on-as-cart-itemenable-free-addon-on-cartoptional:
enable-add-extras(if we want to show the “+ Add extras” button in the “Your Cart” section)
For this solution to work, we need to ensure that Sanity is properly configured:
The creation of the desired Add On Section
The sections here can be created and saved to be used later because they need to be added to the feature menu.
Add the Add On Sections that we want to show in the cart into Feature Menu
Important: The logic uses the paid and free item reference from each Add On Section meaning that doesn’t make sense to create two sections using the same free and paid item and active these two sections in the Feature Menu. If you want to have “duplicated” sections, OK, but use one section per time in the Feature Menu. Using two sections with the same free and paid item will cause trouble to the developed logic as the code will try to validate the two offers at the same time and one offer can invalidate the other. Besides that, a single section is already able to have multiple offered items that accept multiple offers too.
The order of the list defines the order that the sections will be shown on the cart checkout page.
Configure the Add On Section correctly to have the behavior to deal with free items:
“Show as a separate section on cart” (ON)
“Make options in this section as free add-ons” (ON)
“Service Modes”
Here we’ll choose the desirable service modes that we want to offer the promotion
Configure the options (addons) for this Add On Section
Add the paid item (“Option”)
Add the free item (“Free Option”)
Important: the free item needs a PLU with zero price to have the correct behavior and the PLU needs to exist on the desired restaurants to be a valid item
In the “Vendor Configs”
“PLU Type” = “Constantplu”
“Constant PLU” field = “zero PLU”
Obs: for development, we can use the “PLU Type” as ignore, and the product will have zero as the value
Configure the “Menu options that Offer the Free Options Above”
Here we’ll configure the item that will receive the offer and the maximum free items quantity
We can select between “Item” or “Combo” in the list
Example of the “Combo” use case:
In Sanity the items that have an offer are:
1 free item offer for the “Menu 2 pieces regular for 1”
1 free item offer for the “8 Onion Rings”
With that, I’ll have 2 free items available for this cart configuration:
This can be very dynamic (examples):
If we have only the “8 Onion Rings” in the cart for example we’ll have only 1 offer instead
If I remove the combo from the Sanity offer I’ll have only 1 offer for the “8 Onion Rings” that exist inside the Combo
The main idea is: “Do we have an item inside the combo/item that has some offer?” → If yes this will be counted in the offer amount
Configure the “Free Add On Modal” fieldset if wants to show the promotional modal when the user enters the checkout page
The fieldset “Free Add On Modal” will be available for all options in the “Add On Section” and with that, we’ll have one modal for each free item (option)
“Show Free Add-On Modal at Checkout” → if ON we’ll have this modal shown in the cart
This toggle is very useful. If you don’t want an specific modal to be shown, just turn the toggle OFF
The image and description are optional. Title and CTA are required if the toggle is ON.
If none image is selected the modal will show as a fallback the free item image
If some image is selected this image will be shown
To avoid quantity limits for the added items in the cart we need to configure the following on Sanity:
In the example above the user can select only 20 items (individually) in the cart.
This limit will also affect the addons items. Even if we offer 30 free items the user cannot select more than 20 items (in this example). Important:Today this value will only be changed if we change the value in the mentioned field (Sanity) and after that, we have a new deployment of the app on the envs (dev, qa, prod, etc). Change the value without a new deploy will not apply the new value.
Front-end behaviors and Business rules
After all the requirements are configured, we’ll have the following things on the FE UI:
Promotional modal when entering the checkout the first time/journey/order
Basic Rules
Show the modal only for the first time (and always if we have a “new cart”, eg: cleaning the cart and adding the products again)
If the user hits F5 the modals already saw will not be shown on the screen, only the new ones
If we have only one modal ON we’ll not show the modal in the carousel format/approach
For more details of carousel buttons behavior: https://rbictg.atlassian.net/wiki/spaces/IBC/pages/4169040346/Whitelabel+Add+free+extras+modal+on+checkout+page+cart#Task-2%3A-Add-carousel-logic-in-modal-content
The modal will show content for every section that has a matching item (the configured option inside the Add On Section) with an offer on the cart
Checkout sections
In this example, I have the “Add Ketchup” and “Add Sauces” sections. Some rules for this part of the screen:
If the user did not add the free items through the promotional modal he’ll see the free offers on the screen
If click on the free item:
Is the maximum of free items selected in the cart?
Yes - show the paid item in the section
No - hide the section from the screen if the section doens’t have other items to offer
We’ll only show the section if at least one item from the section has an offer
We’ll show only items that have an offer in the section (individually)
Your Cart behavior with free/paid items
The free item will have a description about the maximum of the free items available with the items combined in the cart:
Quantity of the item that offers the free item X sanity free quantity → In this example “The Sandwich” offers 1 free item, so: 1 x 1 = the maximum for Ketchup free is 1
The free item will have 0.00 for the price (will not use any label here because we want to ensure the same consistency between receipt and front-end)
Automatic “balance” of the cart content based on the following rules:
The user cannot pay for an item if he has free items available to select
The user cannot buy additional free items (besides what's been offered)
The app will remove/add free and paid as needed to balance the original quantity on the cart
Remove free and paid items from the cart if the main item (that holds the offer) is removed
Extras modal to edit addons
The user will edit the quantity for the addons by clicking on the “Edit” button that will open the “Add extras” modal
The modal will also respect the rules for maximum free items → In this example the user can select a maximum of 1 Free item and he’ll be able to select the paid item if want more add-ons
The paid item will only be offered if the free is on maximum during the edition in this modal
The edition in this modal doesn’t changes the cart in the background. The edition will be made only after clicking on the “Update Order” button
Troubleshoot
Q: Section with free items is not in the checkout even with an item that has an offer
All the flags and toggles should be ON as showed in the Requirements section
Sanity needs to be configured properly and the right item (that is offering the free ones) needs to be in the cart
If some item used as a free/paid addon in the Add On Section options has an invalid configuration the entire section will be invalid, for example:
Invalid PLU (this can be changed anytime and is not tied only to Sanity. The Whitelabel will check that making a query for the restaurant POS data too. Please, check if all is good with the PLU availability)
Invalid item config
Invalid vendor config (the Whitelabel will use this information to check with the POS if “all is good”)
Q: When I add the free item to the cart I receive the error for “Unavailable item”
Probably the item is not properly configured for the selected store (POS data for restaurants). The PLU for the free item needs to be configured as a valid item for the desired restaurant. More details in: PLU x Item unavailable (analysis)
Q: I added the free item to the max limit and when I added the paid item the paid item was not in “Your Cart” section but the toast appears with the message that the item was added
Probably you put two sections active in the “Feature Menu” (Sanity) that have the same paid and free items configured for different offers. As said in the Requirements section you don’t need two sections for that as the section can have multiple offers for the same item. This is a problem with your configuration and is not considered a bug
Important: The logic uses the paid and free item reference from each Add On Section meaning that doesn’t make sense to create two sections using the same free and paid item and active these two sections in the Feature Menu. If you want to have “duplicated” sections, OK, but use one section per time in the Feature Menu. Using two sections with the same free and paid item will cause trouble to the developed logic as the code will try to validate the two offers at the same time and one offer can invalidate the other. Besides that, a single section is already able to have multiple offered items that accept multiple offers too.
Q: The items in cart (free/paid/item that has the offer) is limited to a quantity of 9 (or X)
We have a configuration for this in Sanity. Take a look at the Requirements section and adjust as you need
Important:Today this value will only be changed if we change the value in the mentioned field (Sanity) and after that, we have a new deployment of the app on the envs (dev, qa, prod, etc). Change the value without a new deploy will not apply the new value.
Q: The free item is not showing zero as the price
You need to use a PLU configured with zero as value. Take a look at the Requirements section
Important: the free item needs a PLU with zero price to have the correct behavior and the PLU needs to exist on the desired restaurants to be a valid item
Environments with valid data to test
Obs: As the environments are very dynamic (anyone is free to make changes all the time) this can be false information at the time you are reading this
Dev PLK CH:
Restaurant: Hofwiesenstrasse 370 (Zurich)
Products with offers: “The Sandwich”, “The Sandwich Menu”, etc
Dev PLK ES:
Restaurant: Vía de la Hispanidad 15 (Saragossa)
Product with offer: “Menú The Chicken Sandwich Mediano”
Dev BK DE:
Restaurant: Im Bahnhof Friedrichstraße Halle (Berlin)
Product with offer: “Snack Salad”