SDK in Custom Applications

spaceBlippar Documentation Centre

Introduction

New Publishing Flow

Lately, with the release of the SDK 2.2.0, we have introduced a new publishing flow for the blipps. Now you don't have to enter the first eight symbols of the SDK license key as the blipp test code to allow your custom application to scan it. You can just select one or several apps available to you for publishing and publish your blipp for them. This makes publishing and un-publishing blipps much simpler and faster and allows us to introduce a new feature: testing blipps in your custom applications. Now you can publish blipps that will run only in your internal application builds without a risk of revealing it to your customers before it is ready to go live.

Blipps published using the new publishing flow can only be scanned with the latest SDK (2.2.0 or newer). However, if you have not moved to the new SDK yet and for some reason cannot migrate immediately there is still an option to publish your blipps for the SDK 2.1.x using the old publishing flow. Please note that the old publishing flow will be turned off eventually (current plan is to support it for three months after the new publishing flow release), so we strongly advise to migrate to the new SDK as soon as possible.

This manual provides detailed instructions for blipp publishing for both older and newer SDKs using the old and the new blipp publishing flow accordingly.

New Hub

Current Blippar hub has been out there for a long time. It was developed several years ago using state of the art technologies of that time. But as it happens with many things, new technologies were introduced lately which will allow the hub to work faster and provide a better experience with improved usability and enriched functionality. So we would like to present you the new, updated and improved Blippar blipps hub: https://blipps.blippar.com/

The new hub is still in the beta stage and it is being tested and improved. This means that there are still some unfixed issues, though these are mostly minor and navigation related. The UI may also change before the final release and additional functionality is likely to be added. However, the new hub already offers better support for the new SDK publishing flow. Here are some of the publishing features, available only in the new hub:

• Simplified UI provides an easier overview of the target applications and countries to publish the blipp for.

• Simplified publishing for the old and new SDK versions. You can now enter several test codes in several test fields to make publishing for the old publishing flow simpler. Unfortunately to support both publishing flows users still need to publish two copies of blipp — one for the old SDK should be published for testing and the other for the new SDK should be published live. And this brings us to the next improvement.

• An option to copy any blipp version into a separate blipp. This feature works both for the Blippbuilder blipps and for custom JS blipps. The support of the Blippbuilder blipps means that now users copy them and open the copy in Blippbuilder and continue using the Blippar visual editor to modify the blipp.

• Faster performance.

With this in mind please try our new hub using your current hub account. The hub can be accessed using your current hub credentials with the following address: https://blipps.blippar.com/

The manual below is the blipp publishing manual updated with the new Blippar Hub UI changes.

New Blipp Publishing Flow for the Blippar SDK Applications (for SDK 2.2.0 and later) in the New Blippar Hub

The key difference between the new SDK publishing flow and the old one is that now you can select the application you want to publish your blipp for instead of using test codes for the same aim. The following manual will explain how to use the new publishing flow.

When creating a new blipp, users have two options:

• Use our visual editor called Blippbuilder

• Use a more advanced and complex Blippbuilder script for creating a complex experience.

While in general both of these options use the same Blippar services for blipp publishing there are some differences in the UI users should be aware of.

Please read the following manual carefully to understand how to use the new publishing flow with the new Blippar Hub.

Note: A new publishing flow will not be available to users, who have no other target applications available to publish to except Blippar app. To have other target applications available for publishing either current user or one of the group members user belongs to has to own an SDK license key.

Important

Blippar app uses the new publishing flow. To publish something for the Blippar app use the flow described below and select Blippar app as a target application.

All blipps published previously for the Blippar app will continue to work as before, there is no need to republish them.

Testing and Publishing a Blipp Created Using "Blippar Script" (JS)

Creating a new JS Blipp

1. Login to hub UI.

2. Hit "Create a Blipp" and select "Blippar Script" from the available options:
3. Upload one or several blipp markers and hit the button "Continue":
4. Upload the zip with your created blipp:
5. As soon as the new blipp is uploaded to the hub you have two options: you can either test the blipp with the Blippar app or one of the applications available to you or you can publish the blipp for the Blippar app or one of the applications available to you.

Testing

To test the blipp:

1. Chose the option "Update Test Publish" from the blipp control menu.

2. Select applications you want to test the blipp with:
3. After the application is selected it will be added to the list of the publishing targets. If there are several App IDs registered with this application name, they all will be listed under the same name. Click on the app name to see all target app IDs. Leave the checkbox checked for the apps you want to test the blipp with and remove the checkbox for the IDs that should not have any access to the test blipp. Press "Continue" to manage blipp test codes on the next screen.
4. Review test codes that will be saved with your blipp to use them later to access the blipp.
5. Add up to 5 more test codes using the "+" button in the upper right corner. Press "Continue" to review blipp test targets and test codes.
6. Review blipp test targets and test codes on the final review screen. Here you can change the list of the target apps and test codes if you notice an error. Note that at this point the blipp is not available for testing yet. Press "Publish to Test" to publish the blipp with the testing code to test with target applications.
7. After pressing "Publish To Test" button wait for a bit while the blipp is published for testing. When it is done, the blipp status screen will be shown. Feel free to use it for blipp testing. Scan the marker or cycle through the markers to chose a different marker to scan.
8. Click "Close" when you are done to return to the blipp management screen.

Publishing

To publish the blipp:

1. Choose the option "Publish to Live" from the blipp menu.

2. Select target applications for your blipp. Same principles as with selecting target applications for testing apply: if there are several app IDs registered for the same application name you can choose app IDs to publish with after selecting the application name. Several target application names can be selected. Please note that if you have already published your blipp for testing previously, the list of target applications will be pre-filled with applications you have used for testing. These applications can be removed if they are not needed. Click the "X" button on the right side from the application name to remove it from the targets list. Press "Continue" to select target countries for the blipp.
3. On the next screen, you can select a list of countries you want the blipp to be available in. Choose "Global" option to make your blipp available everywhere or select "Local to Country" and add countries to a targets list to restrict campaign availability to certain countries. Always publish blipps only to the countries your license permits to publish for. Press "Continue" after target country list is complete to continue to the review screen.
4. Before publishing the blipp, please review target countries in which this blipp will be available and applications that will be able to open the blipp. If you find that you need to change the country or the target app list, it is still possible to do so by pressing the "Change" button next to the list you want to change. At this moment the blipp is not public yet. Press the "Publish" button to publish the blipp.
5. Wait for a bit until the blipp is published. After the blipp is published you will be redirected to the Blipp Status screen which can be used to review blipp status, list of target countries and applications and blipp markers. Use this screen to test the blipp if needed.
6. Press "Close" to return to the blipp management screen. Your blipp is live now!

Managing the "Blippar Script" JS Blipps

Besides testing and publishing "Blippar Script" JS blipps there are various other operations available for users to perform with these blipps. These operations can be performed using two main screens:

• Blipp project management screen

• Blipp History screen

Blipp Project Management Screen

This is a screen where users can manage all blipps created for a single project:

Every blipp on this screen has a horizontal "meatballs" menu button that allows accessing blipp specific actions. The actions available in this menu are:

1. Set Offline — Unpublish blipp. This option is only available for the blipps published live or in testing.

2. View Stats — Access blipp statistics.

3. Version History — Access blipp version history. This is the screen where you can upload a new Blippar Script JS Blipp version and perform various other actions. See next Chapter for more information.

4. Move To... — Move the blipp to a different project (within the same user group/company).

5. Duplicate — make an exact copy of the latest blipp version. This functionality is useful in case you want to create a new blipp using current blipp as a template or if you want to create an exact blipp copy to publish the blipp using the old publishing flow.

6. Delete — Remove the blipp completely.

7. Status — opens the blipp status screen where you can review if the blipp is live or in testing, which apps the blipp has been published for, in which countries and what are the test codes that allow accessing the blipp (if it is on testing).

8. Publish to Live / Publish to test / Update Live Publish / Update Test Publish — blipp testing and publishing commands described in previous chapters.

Blipp History Screen

Blipp history screen can be accessed using the "Version History" option from the project management screen described in the previous chapter. Blippar Script JS blipps also redirect to this screen when users want to edit such blipps.

The main functionality available on this screen is an option to upload a new version of the blipp source code and download the current blipp source code. But besides these, there are various other options available on this screen through the blipp version menu. To access these options click in the top right corner of the blipp version you want to work with.

Here are the actions you can do with blipp versions:

1. Set Offline — Unpublish blipp. This option is only available for the blipps published live or in testing.

2. Status — opens the blipp status screen where you can review if the blipp is live or in testing, which apps the blipp has been published for, in which countries and what are the test codes that allow accessing the blipp (if it is on testing).

3. Publish to Live / Publish to test / Update Live Publish / Update Test Publish — blipp testing and publishing commands described in previous chapters.

4. Restore — Set this blipp version as the current blipp version. The blipp will be updated with the new code copied from this blipp version.

5. Create New Blipp From Version — Create a new blipp using the selected blipp version as the first blipp version. The action is similar to "Duplicate" from the project management screen but allows to create a new blipp form one of the previous blipp versions, not just the latest one.

6. Download Code — Download the source code for the current Blippar Script JS blipp. It can be then used to create a new blipp or a new version of the current blipp.

7. Add Trigger Images — Add more trigger images.

"Add Version" Button and Other Blipp Modifications

On the very top of the blipp history screen, there is an "Add Version" button. Use this button to upload a new version of the source code for the current blipp.

If you need to add new trigger images fro the blipp use "Add Trigger Images" button. This will not create a new blipp version, only add more trigger images for the current blipp version.

If you need to remove a trigger image, hover the mouse over it. An icon with a bin will appear in the top right corner of the marker. Click it to remove the trigger image (marker) from the set of images that can be used to launch the blipp.

If you need to update a set of target countries, applications or test codes for an already published blipp, use "Update Live Publish" and "Update Test Publish" actions. Updating these parameters will not unpublish the blipp, there is no downtime for changing them.

Publishing a Blipp Created Using the "Blippbuilder" Visual Editor

1. Login to hub UI.

2. Hit "Create a Blipp" and select "Blippbuilder" from the options:
3. Upload your marker and hit the button "Continue":
4. You'll be redirected to blipp builder UI. Make the necessary changes to your blipp:
5. Once you have done the necessary changes you will have two options: you can either test the blipp with one of the applications available to you or you can publish the blipp for one of the applications available to you. Press "Preview" button to test the blipp. Press the "Publish" button to publish the blipp to live. Please refer to the chapters "Testing" and "Publishing" for the Blippar Script JS blipps above to get more information about blipp testing and publishing, after the new hub UI is implemented for the Blippbuilder blipps publishing the process will look exactly the same. Please refer to the note below if you see a different UI.

Warning!

Warning! At the moment when this manual was created, the UI for the Blippbuilder blipp publishing was not updated yet. This is expected to be fixed soon. Meanwhile below is the manual for the old hub UI which you may encounter after pressing "Preview" or "Publish" buttons in the Blippbuilder. We are sorry for the inconvenience. If you want to use new blipp test/publish UI, you can still do this from the project management screen.

Old blipp publishing UI for the Blipp Builder

1. To test the blipp note the test code or enter your own blipp test code to test the blipp in your target app. By default, the new publishing flow is hidden but note the checkbox "Use the new publishing flow (SDK v.2.2.0 or newer)" in the left part of the test screen, under the instructions. Tick it to use the new publishing flow and the list of the target applications will be shown. In this list select the application that you want to use to test the blipp. it could be the Blippar app or any application you or your team members have registered. Press the "TEST" button once you are ready. To test the blipp in the Blippar app go to settings and enter the test code there. To test the blipp in your custom app using the SDK use the "setDetectionCode" method before enabling detection. Above: Blipp testing screen with new publishing flow disabled. Above: Blipp testing screen with new publishing flow enabled and a list of target applications available for selection.
2. To publish the blipp live press the "MAKE IT LIVE" button and proceed to the next step.

3. On the next screen, you will see the list of applications for which you can publish the blipps. Currently, this list will contain all applications that you or your group members have registered with the Blippar Developer Portal. When publishing a blipp, publishers can also select to publish it globally or to a limited set of countries (please check your contract when selecting the set of countries to target, violating the contract may result in blipp removal).
4. You can pick and chose your apps where this blipp will be blippable after you hit "GO LIVE". Your blipp should be published now.

Publishing Blipps for the Old SDK Versions (pre-2.2.0)

Introduction

The following manual explains how to publish a blipp if you are still using the Blippar SDK 2.1.x in your application.

We have introduced the old publishing flow as a temporal solution during the early days of Blippar SDK. Please note that old publishing flow will be disabled after the migration period is over (the date will be announced in advance).

When the old publishing flow is used blipps are restricted so that they can only run within certain applications:

• Blipps designed to be published in the Blippar app cannot be published in third-party apps that use Blippar SDK.

• Blipps designed to be published in third-party apps that use the Blippar SDK cannot be published in the Blippar app.

Besides the user experience improvements, one of the other reasons behind the introduction of the new publishing flow is to allow the simultaneous blipp publishing or testing in third-party apps that use the SDK and in the Blippar app.

Note

Please remember that the SDK provides some options for blipp control and communication that can make it impossible to play the blipp designed for the SDK in the Blippar app. Be aware of this and don't make the blipp available to the Blippar app if it is using specific SDK functionality, such as application and blipp intercommunication, as in these cases the blipp will not be detected by the Blippar app even if it is published.

Detection Codes for the Old Publishing Flow

In the old publishing flow, these blipp availability restrictions are controlled using special Detection Codes. Detection Codes are set up when you create and upload your blipps to the Blippar servers.

The Detection Code is defined as the first 8 characters of your Blippar SDK License-Key that was provided to you when you registered your application with us. For example, if your SDK license key is 24d5019300eda2b722fa3ec21a2b86e2f4f1cb47fd697704f04979db8b2d0d795a99464e then your special unique Detection code is 24d50193.

This detection code is specific to the application tied to this SDK License Key and will not work with any other application you create.

You do not need to do anything in your application source code to make this detection behaviour work. It is handled automatically using your License Key when you initialise the SDK.

Publishing a Blipp for the SDK Using the Old Publishing Flow

Publishing the blipp for the SDK 2.1.x and older using the old publishing flow is performed similarly to the way it is done in the new publishing flow. The key difference is on the testing screen. Please follow the instructions for the new publishing flow to the point where the test code entry screen is shown:

• If you have been using Blippbuilder Script to create your blipp, please follow the Blippbuilder Script blipp publishing documentation till step 5 (stop before selecting the "Update Test Publish" action).

• If you have been using Blippbuilder to create your blipp, please follow the Blippbuilder blipp publishing documentation till step 5, press the Preview button on the top right side of the tool.

Do not publish blipp to live if you want for it to be available for the old publishing flow. If you have published the blipp to live, un-publish the blipp using the "Set Offline" action available in the blipp version history and start the publishing process again.

Once you land on the Test Blipp screen (by selecting "Update Test Publish" action in the blipp menu), you must set the blipp detection code to be the first 8 characters of your License Key.

1. Select any target application in the "Choose your target apps" drop-down, this selection is ignored by the old publishing flow:
2. On the "Add Test Codes" screen enter the first 8 characters of your SDK App Key.
3. If you need to publish the blipp for multiple apps, add up to 5 test codes using the "+" button in the upper right corner and set them to the app first 8 characters of the license keys accordingly. Press "Continue".
4. Review blipp test codes on the final review screen. Ignore "Apps" list. Here you can change test codes if you notice an error. Note that at this point the blipp is not available for scanning yet. Press "Publish to Test" to publish the blipp for your custom applications using the old publishing flow.
5. After pressing "Publish To Test" button wait for a bit while the blipp is published. When it is done, the blipp status screen will be shown. Feel free to use it for blipp testing. Scan the marker or cycle through the markers to chose a different marker to scan.
6. Click "Close" when you are done to return to the blipp management screen.

Note

Please note that it does not matter which target application you select during test publishing, the selection will be ignored anyway and only detection code will be considered for the blipps published for the SDK 2.1.x.

Congratulations, your new blipp is ready to go. It is now registered against the detection code and will only be visible in your application.

Publishing the Same blipp for Two Target SDK Applications Using the Old Publishing Flow

When using the old publishing flow to publish the same blipp for several target applications blipp publisher has to enter every application first eight symbols in separate fields on the "Add Test Codes" form.

For example, let us say the client has two SDK licenses, one for iOS and one for Android:

• iOS SDK License key is "12345678...".

• Android license key is "abcdefgh...".

If the blipp publisher wants to publish only for iOS, they need to enter only the code "12345678" on the "Add Test Codes" form. To publish the blipp for both target platforms they should enter the first code in the first field and the second code in the additional field.

You only need to create a copy of the blipp if you want it to be available using both old and new publishing flow. See the chapter "Publishing the Same Blipp for the Old and New Publishing Flow" for the detailed instruction about this.

Publishing the Same Blipp for the Old and New Publishing Flow

If you are using the old publishing flow to publish the blipp then it will not be available for the new publishing flow.

To be able to see the blipp using both publishing flows you will have to create two copies of the same blipp. Here is how:

1. Open the list of your blipps.

2. Instead of opening the blipp you want to copy in Blippbuilder or uploading a new script in Blippbuilder Script, find the three dots next to the blipp name and click on them to see actions menu.

3. Choose "Duplicate" action from the menu.

4. A copy of the blipp will be created in the same project. It will appear as the latest blipp in the top left corner, next to the button "Create Blipp" with a random trigger image (marker).

5. Using the three dots next to the blipp name view blipp history. On the blipp history screen, you can change the name of the blipp by clicking on it.

6. You can upload same trigger images/markers for the new copy of the blipp, as it will be published using the old publishing flow and will not interfere with your other blipp.

7. Now publish both copies of the blipp using the different publishing flows. We recommend keeping the main blipp copy published using the latest publishing flow and a copy using the old publishing flow.

If you need to update the blipp, update the man blipp copy and remove the other copy of the blipp. Then duplicate the main copy again and re-publish it.

Migrating a Blipp From the Old Publishing Flow To the New Publishing Flow

It is pretty easy to migrate your existing blipp from the old publishing flow to the new one. To do that just go through the same steps you would go to update a blipp and use the new publishing flow while doing so.

Migrating a Blipp From the New Publishing Flow To the New Publishing Flow

In an unlikely case when someone needs to make sure that a blipp published with a new publishing flow has to be available to the old SDK (2.1.x), please follow the same steps you would follow to update the blipp and publish it on test code using the first eight symbols of your SDK license key as the test code to make the blipp available to the old SDK.