Quikkly Integration Guide
We're excited that you're interested in improving your app and customer experience with Quikkly! It's super easy to add the Quikkly SDK to your app, but we've put together this short guide to help you make the best choices as you integrate our technology into your app. There are a few design and architecture decisions you need to make according to your own needs - if you've any questions, don't hesitate to contact us and we'll gladly lend you our expertise....
Step1: What are you going to do with Quikkly?
Quikkly offers lots of possibilities to improve user interaction but we recommend you start with simple use cases. Consider how Quikkly can make it easier to connect users, or faster to complete follow actions, payments or purchases. The use case will of course vary with your app and that’s the power of Quikkly.
The outcome or “action” invoked by a scanner code detection can be whatever you want it to be. Most developers will want to create an action in your own app, but Quikkly also offers a suite (link) of ready-made ‘actions’ to suit common use-cases, such as playing a song on Spotify, watching a video on YouTube or following a user on Twitter. If you are creating your own action, the Quikkly SDK will return the number encoded in code which you can then process in your app to complete the action.
STEP 2: Designing your scannable code
Quikkly codes are the smartest and most on-brand scannables in the world. We offer a variety of basic templates/layouts that you can customise by adding an image such as your own logo. More advanced implementations could consider adding a user’s profile photo but that will require you to be able to pass the resource location into the code generator. If you’d like to discuss a fully custom design, contact us and we can help you create a unique design.
We’ve got three standard templates that arrange the scannable part of the code around your logo or image. Choose a horizontal, vertical or surround template that suits the shape of your image to get started.
Quikkly lets you make the most of your code by giving you control over a number of key elements in the code. When generating a code, your app can instruct the Quikkly SDK to set the color value of the code parameters such as Frame colour, Dots colour, etc.
Remember: the dots are the critical part of the code. Scanning will not work reliably if the dots do not stand out from the background. Ensure that there is a strong degree of contrast between the colors you set.
To make it faster to create your first custom scannable, we’ve created a simple tool here to help get you started. This will let you set the basic elements of the code and pass them to the SDK to generate your scannable. If you’re unsure on your code design, just contact us and we can help - we’ve designed thousands of beautiful codes to date.
Depending on the template chosen, you will be able to generate billions of unique codes. And we’ve got more layouts coming soon which can address quintillions of unique items. If you’ve got a question about precisely how many items can be addressed, just contact us.
Step 3: CUSTOMISE YOUR SCANNER UI (or USE OUR DEFAULT)
The Quikkly SDK allows you to choose between:
a lightweight UI provided by Quikkly that includes a target frame and progress bar, or
no UI at all so you can define your own UI to fit more closely with your own app styling.
In either case, it’s mandatory to include Quikkly attribution somewhere on your scanning screen using the supplied logo or other approved execution.
As best practice your viewfinder should provide crosshairs, masking or some form of indicator to encourage users as to where in the viewfinder you want them to place the code being scanned. We also recommend you provide a flashlight icon so users can turn on the flashlight in low light.
An example of a custom viewfinder is shown here:
Remember: adding a scanner may mean your app needs new permissions, to access the camera. You may wish to add a contextual prompt to users to explain why this permission is needed.
Upload from Gallery
You can also enable your users to detect codes from photos/screenshots saved to their camera roll/gallery. Instead of invoking a live viewfinder, your app can ask for access to the camera roll and pass photo frames into the code detection module in the Quikkly SDK.
STEP 4: Decide how your users will find the scanner/Link to the code
The most successful integrations ensure that the scanning/code features are easily accessible as a prominent part of the user experience where they are most relevant. We also recommend you consider some form of coach-marks to introduce the feature to your users the first time they open the app after you add the feature.
A visible, conventional icon to initiate your scanning UI is the best approach to enabling user discovery. Here are some examples of how you might add the link to the scanner. Also, a visible convenient icon to generate and display your branded Quikkly code will ensure that users can access their code easily.
STEP 5: DO YOU WANT TO GENERATE THE CODE LOCALLY OR REMOTELY?
Quikkly codes can be generated on our servers, or locally on the device within the SDK. You can choose which approach suits you best, depending on your use case.In cases where you need ultimate performance, or need to operate offline, generating codes locally within the Quikkly SDK can be the optimal choice. This involves your app instructing Quikkly SDK to generate a code with a particular configuration (e.g. template 2, color set 3, etc.) and passing a number to the SDK, such as the number of the user the code is for. The Quikkly SDK generates the coded dots representing that number and returns a code with those dots, in SVG format, back to your app for display. This process does not involve a round-trip to Quikkly’s servers and therefore results in the fastest generation of the code. However the code is not stored on Quikkly’s servers and not backed up by Quikkly.
Alternatively, your app can request a code to be generated by our servers using parameters you provide. The parameters required for generating codes are documented here. All tags generated on our servers are stored for future use and are available for download from S3 if required. For this, your app can either instruct the Quikkly SDK to generate the code remotely via our APIs, or you can access Quikkly’s code generation APIs directly.
STEP 6: YOU'RE READY TO HOOK UP YOUR ACTION & CODE
Once you've made some basic decisions about your Quikkly integration, it's time to connect your code generator and the scanner into your app and link the results of the scanner to your desired action. Full details on how this works are found in our developer documentation here.
STEP 7: Monitor your codes
Now that you've added scanning to your app, it’s important to keep an eye on how it's doing for you. Quikkly gathers data on events including code generation, successful scan and so on. If you’re using Quikkly Cloud, these events are always up to date for your app/code and you can use our insights dashboard to keep track of what’s going on. Alternatively you can query these insights as needed. If you’re using Quikkly Local, we recommend you include scanning event tracking in your app analytics.