Code Templates and Styles

Each Quikkly code contains some dots or dashes to encode data, and images, logos or other styling to match your brand. The codes come in a variety of styles: squares, rectangles, circles and more.

Templates

The Quikkly SDK ships with over 40 standard templates. You can preview them at Try Sample Codes.

The template determines the position, size and shape of the borders, images and data dots.

Each template has an ID (in some places called type), like template0001style1, or template0013style3. This ID is passed to the code generation APIs to select the layout.

Data Payload

Quikkly codes encode a single large number as data. This number is passed in during code generation.

After a successful scan, the Quikkly SDK returns both the template identifier and data number found.

Most templates can support up to 64bit numbers: 0 to 18,446,744,073,709,551,616, or 18 billion billions. Some smaller templates contain fewer data dots, and can support data payloads with 32bit (4 billion) or smaller numbers.

template0002style3 template0001style1 template0013style2
64bit data
18 billion billion codes
32bit data
4 billion codes
24bit data
16 million codes

Storing URLs and text

As the maximum data payload of a Quikkly code is 64 bits or 8 bytes, you cannot store an URL, long usernames, or large blocks of data in the codes.

Instead, store an user or object ID number, and make your app look up the rest of the data from your web server.

You can store very short text in the code by converting it into a number, and converting backwards from a number after scanning. With the 64bit templates, you can store up to 16 hexadecimal (0-9 A-F) characters, approximately 10 full English alphabet (0-9 A-Z a-z) characters. The SDKs offer helper functions to convert between the data number and text in any alphabet.

Style Options

In addition to selecting the template, you can customise the colors and images in the code.

Colors

There are five color settings. Not all templates have all of the layers, and some use them in different ways. Experiment with different colors to see which controls which part of your chosen template.

  • Border: Solid border surrounding the entire code.
  • Background layer: Usually inside the border, behind the image and dots.
  • Mask layer: Usually inside the border, behind the dots, but in front of the background. Has a cut-out for the image.
  • Overlay layer: Usually surrounds the image as an inner border, or some other area on the code.
  • Data: Color of the data dots or other symbols. Can provide multiple colors, which are chosen randomly for each dot.

Not all color choices scan equally well. The scanner works in grayscale, and requires strong contrast between the background and the border and data dots. Make sure the colors you choose have different brightness levels after being converted into grayscale.

Images

Most templates have a space for a single image, and a few have space for two (image and logo).

There are two ways of providing images:

  • A web URL. The URL is copied into the generated code SVG file. The SVG renderer that you are using to display the codes will have to download and display it. If you are displaying the code in a web browser or mobile WebView, it will work well, but may not work on offline devices.
  • A local file. SDK reads the file, converts it into a “data URI”, and inserts a full copy of the image data into the generated code SVG file. This SVG file can be rendered offline and even if the original is no longer available.

Warning: Avoid using file:///Users/yourname/Pictures/kitty.png or similar local file URLs. This URL will be copied into the SVG file, and it will render in a browser on your computer, but won’t work on any other computer. Instead, use the SDK methods that insert a full copy of the image data into the SVG file.

Image Fit

Some images may have different aspect ratio than the space for it in the template. You can control the image placement with the “image fit” parameter:

  • Meet: Fit and center inside the box, keep aspect ratio. May leave empty space around image.
  • Slice: Fit and center to fill entire box, keep aspect ratio. May crop edges of the image.
  • Stretch: Stretch the image in both dimensions to fit it into the box.

If you are inserting photos, then “slice” usually looks best, and if you are inserting logos with a solid background color then “meet” usually looks best. “Stretch” never looks best ¯\_(ツ)_/¯.

original meet slice stretch
logo meet slice stretch

Dot Join

Most templates support an optional “dot join” setting. This connects neighbouring dots, so that the code appers to be composed of short lines instead of individual dots. The join can be selected as a style parameter during code generation.

Rectangular codes support horizontal, vertical, left-diagonal and right-diagonal join, and all combinations of these.

horizontal horizontal horizontal
horizontal vertical both diagonals

Circular codes support only join along the circle - use “horizontal” to specify that.

nojoin join
No join "Horizontal" join

Warning: Not all templates support all dot join options. The SDK does not prevent you from using it, but the scanning reliability will suffer.

All standard templates that ship with the Quikkly SDKs do support horizontal and vertical dot join. Those with small dots also support diagonal joins. Custom templates may support none.

Please let us know if you wish to use dot join.

Custom Templates

If none of the default templates match your needs, you can commission us to build a custom template.

One example of custom codes we have built is Pincodes for Pinterest:

Pincode

Benefits of a custom template include:

  • Complete freedom in styling the code.
  • The codes are not readable by apps using the standard Quikkly SDK, only your private version.
  • We remove the default templates and optimize the scanner performance for your template in particular.

If you are interested in custom templates, please contact us to discuss further. It is helpful if you can include a sketch or mockup of the design you are thinking of, and how many bits of data (possible unique data numbers) your code must support.