The Flowcode API is commonly utilized to provide a Flowcode Generator within a proprietary platform or application, whether for internal or external use. Effective development of such a generator requires careful consideration of several key factors. The 2 primary key factors are Scan Destination and Design Customization.

Scan Destination

Scan Destination refers to any URL, SMS, Phone Number, Email, Venmo or even Wifi access. Relevant information gets embedded into the Flowcode’s generated code consumable by the end user. The Flowcode Generator can accommodate a developer's use case, whether they require every code to scan to a predetermined destination or prefer to allow end users to specify it. The main impact on the developer's application is the inclusion or exclusion of an input field in the form for the scan destination URL. Here is a list of the most commonly used Scan Destinations that are supported by Flowcode.

Destination Type	Protocol	Required Params	Optional Params	Example
SMS	sms:	phone number	body	sms:1234567890;?&body=hello%20world
PHONE	tel:	phone number	N/A	tel:1234567890
EMAIL	mailto:	email address	subject, body	mailto:example@email.com?subject=test&body=hello%20world
VENMO	venmo://	recipient	amount, note	venmo://paycharge?txn=pay&recipient=john-doe&amount=10&note=testing
WIFI	WIFI:	SSID (S), security (T), hidden (H)	password (P)	WIFI:T:WPA;S:my-network;P:p@ssw0rd;H:true;

Customization

The aim of exposing Flowcode API to the external consumer is to provide them with an opportunity to generate the codes as per their branding or design philosophy. It is common for an external consumer to require a fixed design that aligns with their brand. Here is the step-by-step guide to designing a relevant design as per the required branding guidelines.

Generating Code with Fixed Design

To generate codes with a consistent design, the first step is to work with Flowcode to develop a design that meets the application's requirements. This can be done using the UI in a DIY fashion or by requesting a custom-designed code from one of the available designed templates. Once the design is finalized, the application needs to obtain the studio_configuration_id associated with the design. This ID will be used to generate codes with the fixed design.

To generate codes with a fixed design using Flowcode, follow the below instructions:

1. Develop a design that meets the application's requirements using the Flowcode UI or by requesting a custom-designed code from a designer.
2. Obtain the studio_config_id associated with the design from Flowcode.
3. When making requests to the Flowcode Generator, include the studio_config_id as a query parameter. The requested URL will be in the following format:

                       
                           https://gateway.flowcode.com/v3/codes/generator/static
                               ?url=https://example.com&studio_config_id={your_studio_config_id}
                       
                   

Multiple Code Design Options

To provide more flexibility to end-users in generating codes while maintaining brand consistency, multiple suitable designs can be developed using the Flowcode platform. End-users can select one of the available designs from the form, and its corresponding studio_config_id will be sent as a query parameter in the Flowcode Generator request.

To provide flexibility to end-users in generating codes while maintaining brand consistency using Flowcode, follow the below instructions:

1. Develop multiple suitable designs using the Flowcode platform that align with the brand as briefed in the previous section.
2. In the application form of the consumer website, provide end-users with an option to select one of the available designs.
3. When the end-user selects a design, include its corresponding studio_config_id as a query parameter in the Flowcode Generator request.
4. The Flowcode Generator request URL will be in the following format:

                       
                           https://gateway.flowcode.com/v3/codes/generator/static
                               ?url=https://example.com&studio_config_id={selected_studio_config_id}
                       
                   

5. The embedded generator will use the selected studio_config_id to generate a code with the corresponding design.

By following the above instructions, an application can provide more flexibility to end-users in generating codes while maintaining brand consistency using the Flowcode platform. This will help in catering to the end-user's needs while ensuring that the brand's consistency is maintained across all the generated codes.

Theme Customization Options

The Flowcode platform offers a limited set of customization options that can be used to allow end-users to independently tweak certain design elements of the code. These customization options include color, background color, logo image URL, logo image height, logo image width, data pattern shape, call to action text at the top, and call to action text at the bottom. Application developers can expose any subset of these options as fields on their form, giving users the flexibility to control some design elements while others remain fixed. The following are the available customization options in the Flowcode platform.

• color: Foreground color of the code, formatted as hexadecimal
• background_color: Background color of the code, formatted as hexadecimal.
• logo_image_url: URL to an image to use as the logo in the center of the code.
• logo_image_height: Height of the logo image.
• logo_image_width: Width of the logo image.
• data_pattern_shape: Shape of the data pattern, which can be one of square, diamond, circle, or default.
• cta_text_top Call to action text at the top of the code (maximum of 37 characters).
• cta_text_bottom Call to action text at the bottom of the code (maximum of 37 characters).

The consumer has the option to expose any subset of the available customization options as form fields within their application. This allows the end-users to selectively control certain design elements while other aspects of the design remain fixed. This enables a greater degree of flexibility and personalization in the code-generation process. Here is how the form can be utilized and what relevant API calls would be.

The example illustrates a scenario where an application developer exposes a limited subset of the customization options to the end-users, such as foreground and background color, and call-to-action text at the top and bottom of the code. Other options such as data pattern shape and logo customization are withheld and remain fixed. The Flowcode Generator URL for this example is formatted with the selected options as query parameters. The URL is constructed as follows:

            
                https://gateway.flowcode.com/v3/codes/generator/static?url=https://example.com&color=%2333B4FF
                    &background_color=%23FFFFFF&cta_text_top=SCAN%20ME&cta_text_bottom=SCAN%20ME
            
        

In a Nutshell

To put it in technical terms, the embedded generator in your application serves as a customizable form that maps input fields to query parameters which are appended to the Flowcode Generator endpoint. The level of code customization options available to the end users is determined by the fields you choose to expose on the form. Here is an example of a consumer application built over Flowcode API that provides multiple customization options to generate a code.

To preview the code, the user triggers a GET request to the Flowcode Generator endpoint by taking a specific action such as clicking a preview button. The Flowcode image is then rendered within your application based on the input values provided in the form. As an example, consider a scenario where the scan destination (flowcode.com) and the code design based on a specific studio_config_id are fixed. When the user clicks the "preview" button, the code is rendered with the specified design and scans to the fixed destination (flowcode.com).

Recommendations

To round up this guide we would like to share with you some recommendations for building your generator:

• Reserve enough real estate on your page to showcase the code. Users should be able to see the details without having to zoom in.
• For fields with multiple options, show all options instead of hiding them in dropdowns. Dropdowns can create friction leading to users not using certain features.