Microsoft Tag Scanning SDK for iphone & Android Apps

Transcription

1 Microsoft Tag Scanning SDK for iphone & Android Apps This document provides an overview of the functionality of the Microsoft Tag Scanning SDK, used to integrate Tag scanning into mobile apps on the ios and Android mobile platforms. The Microsoft Tag Scanning SDK is designed to be flexible so that you can integrate Tag experiences in the same manner as the Microsoft Tag app or simply, the Tag app (previously called, Microsoft Tag Reader), or create unique experiences for Tags that you are associated with and that are accessible only from your app. Contents Definitions... 2 Overview... 5 Component Overview... 5 System Requirements... 5 View Finder... 5 Experience Handler... 6 Creating Custom Payloads... 7 Additional Components... 8 SDK Keys... 8 Offline Tag Decoding... 8 Client History... 8 Localization... 8 Location Information... 8 Privacy Requirements... 9 Branding Requirements... 9 Getting Started... 9 What Types of Tags Do You Want to Decode?... 9 Getting with the - Android Software Requirements Installing the Required Software Configuring Eclipse Configuring ADT... 11

2 Getting Started with the Code iphone Software Requirements Installing the Required Software Configuring Xcode Definitions Microsoft Tag app or the Tag app (previously, Microsoft Tag Reader Application ) Refers to the Tag reading app issued by Microsoft. This app is built using the Microsoft Tag Scanning SDK. Tag Types The concept of Tag ownership was introduced to enable developers to create custom experiences for Tags that they own. Below are the defined Tag types and approperate action for each Tag type. Tag Type Definition Requirements Associated Tag Tags created using the Tag account that includes the app s Commercial SDK Key. Tags created by any other Tag account, but which have been linked to the app s Commercial SDK Key through the exchange of the app s ID (to perform such link, contact [email protected]). o o All Tags need to be created via the Tag System and must be associated with an experience that will be displayed when they are scanned by the Tag app (or another app that supports Tags). On a per-tag basis, when Associated Tags are scanned by the app, they can be handled via a custom experience (that is, one defined by the app) or a standard experience (that is, handled by the Experience Handler in the Tag Scanning SDK). In-Context Tags Tags that are created by a thirdparty Tag account and are printed in a company s publications, or on products or signage in a company s store. (For example, Tags printed on product packaging sold at, or shelf talkers placed in, a o o A company can choose whether to handle In-Context Tags within their app. If a company chooses to support In-Context Tags, in order to provide a consistent experience for Tag creators, regardless of which app scans their Tags, then: Applications must not interfere with the standard experience for the Tag that is handled by the Experience Handler Apps must not target, insert, or display

3 company s store.) any information or advertisements based off of the Tag content of any In- Context Tags If Microsoft provides updates to the Microsoft Tag Scanning SDK, the company must update their application within 180 days of the release of the update. If the application is not up to date within 180 days, the Experience. Handler may handle the third-party Associated Tag as unsupported experiences. o If a company chooses not to support In- Context Tags, the Experience Handler will handle them as unsupported experiences. Out-of- Context Tags All other Tags created by thirdparty Tag accounts. o o The Microsoft Tag Scanning SDK is intended to be used to scan Tags that were created by the owner of the app (Associated Tags) or that a user thinks of as being associated with the app (In-Context Tags). It is not intended to be used to create a general purpose application that can scan all Tags. Microsoft expressly reserves the right to provide the unsupported experience for any Out-of- Context Tags scanned by the app. Companies must not market their apps in a manner that would indicate that their apps are intended to, or can decode, Out-of- Context Tags. o If an Out-of-Context Tag happens to be scanned by an end-user, then there are two possible outcomes: If the app does not support third-party associated Tags, the unsupported experience will be launched. If the app does support In-Context and Out-of-Context Tags, the standard experience for the Tag can be launched, rather than the unsupported experience. As above, the app cannot interfere with the default handling of the Tag by the Experience Handler, nor target, insert, or display any information or advertisements based off of the Tag content.

4 View finder The view finder is used to initiate the Tag scanning process. The Microsoft Tag Scanning SDK provides two ways to use a view finder: using the default view finder that comes with the SDK or creating a custom one. The default view finder provides all of the necessary functionality to start the Tag scanning process. It only requires a few lines of code to start using and meets all of the branding and privacy requirements for Microsoft Tag. Developers can also create their own view finder and integrate Tag scanning. Image frames from the camera (or from memory) can be passed to the Tag decoder and initiate the Tag scanning process. Experience handler is used to host the content from a Tag scan. Similar to the view finder, there are two kinds of experiences: custom and default. A custom experience is one in which your app displays exclusive content or includes other unique functionality that would not otherwise be available in other apps. It is important to note that custom experiences are only available for Tags that are created by the app owner or Tags that the app is affiliated with (referred to as first-party Tags, below). Enabling a custom experience for your app is the primary purpose of the Microsoft Tag Scanning SDK. Custom Experience. A custom experience is an experience for the Tag that is specific to the scanning app, and which is generally handled directly by that app. Standard Experience. A standard experience is an experience handled by the Tag Experience Handler which is part of the Microsoft Tag Scanning SDK, and provides an experience similar to the experience that would occur if the Tag was scanned by the Tag app. Unsupported Experience. If the Tag is not supported by the app, the Microsoft Tag Scanning SDK will display a message to the scanner explaining that the Tag is not supported and/or might also launch the Tag app to view the experience associated with the Tag. Tag SDK Keys An SDK key is issued per app that enables Tag scanning functionality for the SDK. There are two types of SDK Keys: Commerical SDK Keys: a production Tag Scanning SDK key issued by Microsoft to a company that enables a Distributable app to make use of the Tag Resolution Service. A unique Commercial SDK Key will be provided for each Distributable app. Trial SDK Key: a key for use by a company when developing and testing apps using the Microsoft Tag Scanning SDK, prior to obtaining a Commercial SDK Key. Trial SDK Keys provide up to 100 Tag scans per day.

5 Overview The Microsoft Tag Scanning SDK enables developers to create mobile apps that integrate Tag scanning functionality. This not only provides an improved user experience for end users, but also enables apps to provide unique experiences for Tags that they create (Associated Tags). Depending on the desired functionality, there are multiple ways to integrate the Microsoft Tag Scanning SDK. The SDK primarily consists of two main components: the view finder and the experience handler. For both of these components, developers have the option to choose whether to use the components provided by the SDK (known as the default) or create a component. Below a high-level walkthrough of all the available options and functionality. This overview document will first describe different Tag types and the different types of experiences that are available per Tag type. Next the document will describe the experience handler and the types of experiences that are avaialable in the experience handler. Next the document will describe the view finder. Finally the document will describe important topics such as privacy, location settings, and other common issues faced by app developers. Component Overview The Microsoft Tag Scanning SDK consists of two primary components: the view finder and the experience handler. The view finder is used to detect a Tag and launch the experience from the Tag. The experience handler is used to render the experience from the Tag. System Requirements ios: 4.0 and later Android: 1.5 and later View Finder Developers have two options for setting up a view finder. Developers can use the default view finder provided by the SDK or create their own. The choice of view finder (either default or custom) has no impact on the type of experience or the type of Tags that can be rendered. Default View Finder Using the default view finder provides an easy solution for integrating Tag decoding. The view finder meets all of the branding and legal requirements of Tag usage. The default view finder is not customizable. It must be integrated into the app as provided. Below is a screenshot of a view finder for ios and Android.

6 Figure 1 Default view finder. Among other things, the default view finder contains an information button that links to information about Microsoft Tag and describes important privacy information related to Microsoft Tag. Custom View Finder The Microsoft Tag Scanning SDK also enables developers to create their own view finder and pass image frames to the Microsoft Tag Scanning SDK. These images are then analyzed to determine if they contain Tags and launch experiences associated with the Tags. Experience Handler The type of Tags you choose to decode in your app largely determines the type of experience handler you will be able to use in your app. Default experience handler: The default experience handler can be used to decode the experience connected to all Tag types. It is important to note that no component of the default experience handler is customizable. The UI as provided in the Microsoft Tag Scanning SDK must be used as-is. Using the default experience handler, you can choose to display only associated tags, in which case users view the experience connected with the Tag. If you choose not to display associated Tags, when a user scans a non-associated Tag (in-context or out-of-context Tags), the user is taken to a page instructing them to download the Microsoft Tag app.

7 Figure 2 Example of the page directing users to download the Tag app. Custom experience handler: A custom experience handler refers to an app providing its own experience for a set of Associated Tags. It is important to note that the custom experience handler can be used to decode only Associated Tags with custom payloads. All other Tags must be decoded with the default experience handler. When the user scans an Associated Tag, the Microsoft Tag Scanning SDK returns the custom payload from that Tag to the app. Using this custom payload, the app can trigger a unique experience for that Tag. Only the app that is associated with that Tag can receive the custom payload. Creating Custom Payloads Custom payloads enable unique experiences to be launched for apps that are associated with those Tags. Non-associated apps (that is, any other app) scanning those Tags do not receive the custom payload and launch the experience connected to the Tag, typically a URL. Custom payloads can only be created using the web service API. To use the web service API, request a web service API key. The Microsoft Tag Scanning SDK includes a code sample for how to create Tags, and custom payloads, using the web services API.

8 Additional Components SDK Keys The SDK Key is used to grant permission to enable Tag scanning and identify Tag apps on the back end. There are two types of SDK keys: Trial SDK Key Enables you to try out the SDK to determine if you would like to create an app using the Microsoft Tag Scanning SDK. As per the terms of use, app developers are not allowed to go public with an app that uses the Trial SDK Key. The Trial SDK Key limits Tag scanning to 100 scans per day. If over 100 Tags are scanned by the app in a given day, any subsequent request is rejected by the Tag service. Commercial SDK Key Enables you to publically issue your app using the commercial SDK Key. There is no scanning limit on the Commercial SDK Key. Offline Tag Decoding Occasionally, Internet connectivity might not be available when scanning Tags. The SDK provides the ability to launch a Tag experience if the Tag cannot initially be decoded. The Tag experience can be launched from a history object. Client History The Microsoft Tag Scanning SDK exposes history metadata in the HistoryInfo object. You can use this history metadata to build a history UI from which end-users can open previously-scanned Tag content. If you want HistoryInfo available for your app, set TagContext.setFetchHistory to true. Localization The Microsoft Tag Scanning SDK supports the following languages. English Chinese Simplified Turkish Italian Spanish Korean French On Android and ios platforms, the SDK will default to the localization set on the end user s mobile device. Location Information The end user must be given a choice whether to use location information when scanning Tags. On the ios platform, this is managed through platform-level prompts. On the Android platform, the Microsoft Tag Scanning SDK contains an option to collect location information. The Microsoft Tag Scanning SDK

9 will still function if the user deactivates location gathering at the platform level. However, as a best practice, apps must not deactivate location information capture on behalf of the user. Location information is necessary because some Tags depend on location information being available from the clients. To ensure that the best possible location fix is available, the Microsoft Tag Scanning SDK should be activated as soon as possible after the app is launched. Privacy Requirements App developers must adhere to the privacy requirements as defined in the Tag privacy requirements guidelines. Branding Requirements When using a custom view finder, applications must adhere to the branding guidelines highlighted in the Microsoft Tag branding requirements document. Getting Started Below is a brief walk through of how to use the Microsoft Tag Scanning SDK. Please refer to the code samples that are included in the Microsoft Tag Scanning SDK. The code samples highlight all major use cases of the SDK. 1. Setup. 2. You must be provided a Tag SDK Key which enables Tag scanning functionality. Each app key is unique per developer and must not be shared, as per the legal agreement. The app key, version, and context must be set within Tag Context before Tag Scanning will operate. Please contact Tag support if you are having issues with the SDK. 3. Choose the type of Tags you like to decode in your app. For more information, see the What Types of Tags Do You Want to Decode? section, below. 4. Choose the type of view finder. For more information, see the Launch the View Finder section, below. What Types of Tags Do You Want to Decode? The types of Tags that are to be decoded in the app will determine how the Microsoft Tag Scanning SDK can be integrated into the app. Do you want to decode In-Context and Out-of-Context Tags? Refer to definitions for In-Context and Out-of-Context tags. Decoding these types of Tags lets your app decode Tags that you did not create. The option to decode these types of Tags is set per app key and is set on the server. Contact the Tag SDK team to set this option.

10 If you do decide to decode In-Context and Out-of-Context Tags, the experience must be handled using in the Tag default experience handler (see below). The Microsoft Tag Scanning SDK does not enable you to decode the Tag in a custom experience handler. If you decide not to decode In-Context and Out-of-Context Tags, users scanning these types of Tags are directed to a page instructing them to use the Tag app to view the contents of the Tag. See Figure 3, above. Do you want to provide a unique experience for Associated Tags? Providing a unique experience for Associated Tags enables users scanning the Tag with your app to have a different experience than other users using the Tag app to scan the same Tag. If you want to provide a unique experience for your app for your Tags, you must provide a custom payload for the Tags. For more information, see the Creating Custom Payloads section, earlier in this document. Using custom payloads, you can trigger unique experiences in your app. The custom payload is only available to your app. If you do not want to provide a unique experience for your set of Tags and just want to render the default experience associated with the Tags, you must use the default experience handler. Getting Started with the Code for the Android Platform This section describes how to set up your development environment for the Android platform. Software Requirements To use the Microsoft Tag Scanning SDK to create Android apps that work with Tag, you must have the following software installed: Java Development Kit (JDK) Android SDK for Windows Eclipse IDE for Java Developers Android Development Tools (ADT) plugin for Eclipse On mobile devices, the Microsoft Tag Scanning SDK supports Android versions 1.5 and later. Installing the Required Software 1. Copy the Tag Scanning SDK files to a local folder. 2. In your local folder, double-click Jdk-6u24-windows-i586.exe to install the JDK. A wizard guides you through the installation. 3. Create a folder (for example, C:\tools) where you want to install the Eclipse IDE for Java Developers. 4. Extract the contents of Eclipse-java-galileo-SR2-win32.zip into the folder you created in step 3. The Eclipse files are extracted to an \eclipse subfolder (for example, C:\tools\eclipse).

11 5. Extract the contents of Android-sdk-windows.zip into the folder you created in step 3. The Android SDK files are extracted to an \android-sdk-windows subfolder (for example, C:\tools\android-sdk-windows). 6. Create a folder to install the ADT plugin for Eclipse (for example, C:\tools\adt). 7. Extract the contents of ADT zip into the folder you created in step 6. Configuring Eclipse 1. In the subfolder you created for Eclipse (for example C:\tools\eclipse), double-click Eclipse.exe to start Eclipse. 2. On the Help menu, click Install New Software. 3. In the Install dialog box, click the Add button. 4. In the Name box, type ADT Plugin, and then click the Local button. 5. In the Browse for Folder dialog box, select the folder where you installed ADT (for example, C:\tools\adt), and then click OK. 6. In the Available Software dialog box, select the Developer Tools box, and then click Next. 7. In the Install Details dialog box, review the items you are about to install, and then click Next. If you are prompted for a namespace, select the default option. 8. Read and if you accept the license terms, click Finish. 9. In the Software Updates dialog box, click Yes to restart Eclipse. Configuring ADT 1. To start Eclipse if it is not already running, in the C:\tools\eclipse folder, double-click Eclipse.exe. 2. On the Window menu, click Preferences. 3. In the left panel, click Android. 4. Click the Browse button and browse to the folder where you installed the Android SDK (for example, C:\tools\android-sdk-windows). 5. If a certification warning appears, click to accept it. 6. Click Apply, and then click OK. Coding Quick Start Android The code required to integrate Tag into your app can be quite minimal. The steps involved are: Initialize Tag with your app key Create a ScanListener subclass Launch the Tag viewfinder to scan for Tags Initialize Tag Before you can use Tag, you need to initialize it with your app key. This is done with a call to TagContext, as follows: TagContext.getInstance().initialize( <APP_KEY>, <APP_VERSION>, getapplicationcontext());

12 Implement a ScanListener Subclass The ScanListener class contains a set of delegates that fire to allow your application to track the status of Tag scanning. While there are many callbacks to alert your application to different events, only the oncomplete method is abstract and must be public void oncomplete(completionstatus status, Throwable error, Object context) { Log.i("Sample", "Tag scanned with status of " + status.tostring()); } Launch the View Finder To scan for Tags, you simply launch the drop-in view finder with single call to TAGContext.launchViewfinder. This will launch the default view finder activity, scan for Tags, and display the results when a Tag is found. The call takes as input the ScanListener: TagContext.getInstance().launchViewfinder( parentactivity, scanlistener, callbackcontext); Note that the view finder must be launched from a parent activity. As such, you cannot launch your app directly into the view finder as the initial experience. For more examples on using Tag, please check the API reference documentation and the sample apps. Getting Started with the Code for the ios Platform This section describes how to set up your development environment for the ios platform. Software Requirements To use the Microsoft Tag Scanning SDK to create iphone apps that work with Microsoft Tag, you must have the following software installed: Xcode version 4.0 or later Installing the Required Software 1. Copy the Tag SDK files to a local folder. 2. Copy all of the header (.h) files, the TagCoreResources.bundle folder, and the static library libtagcore_ios.a into your project.

13 Configuring Xcode 1. Set the target for your app to ios Device. 2. In the Build Settings tab, under ios Deployment Target, select ios version 4.0 or later. 3. Under Other Linker Flags, enter -ObjC. Note For the first compiled class that uses a Tag SDK component (for example, your AppDelegate class) use an.mm file name extension. 4. Add the following frameworks: AddressBook AddressBookUI AudioToolbox AVFoundation CoreFoundation CoreLocation CoreMedia CoreTelephony CoreVideo Libiconv.dylib QuartzCore UIKit Foundation CoreGraphics Coding Quick Start - ios The code required to integrate Microsoft Tag into your app can be quite minimal. The steps involved are: Initialize Tag with your app key Implement the TAGScannerDelegate protocol Launch the Tag viewfinder to scan for Tags A convenience header file Tag3ai.h is provided that includes all the necessary header files to use Microsoft Tag. Simply add the following line to any class file you intend to use Microsoft Tag with: #import "3aisdk/Tag3AI.h" Initialize Tag Before you can use Microsoft Tag, you must tell Tag what your app s version number is then initialize it with your SDK key using the applicationstart: selector on the TAGContext class: NumVersion ver = { 1, 0 }; [TAGContext properties].applicationversion = ver; [TAGContext applicationstart:@"xxxxx-put_your_app_key_here-xxxxx"];

14 Implement the TAGScannerDelegate Protocol Microsoft Tag informs your app during each step of the scanning process for every frame it scans. You receive these scanning events by implementing the TAGScannerDelegate protocol. While there are many events possible, the only required selector to implement is: - (void) experiencecompletedwithstatus:(tagcompletionstatus)status anderror:(nserror *)error withcontext:(void *)context Launch the View Finder To scan Tags, you simply launch the drop-in view finder with single call to TAGContext s launchviewfinderintonavigationcontroller:fordelegate:withcontext: selector. This will push the view finder onto your navigation controller stack and send back TAGScannerDelegate events to your delegate. [TAGContext launchviewfinderintonavigationcontroller:self.navigationcontroller fordelegate:self withcontext:nil]; For more examples about using Microsoft Tag, check the API reference documentation and the sample app, SimpleTagSample Tag for ios FAQ Q: When initializing Tag, we crash with the exception unrecognized selector sent to NSString on the call selector applicationstart:. What is the problem? A: Tag uses some categories on NSString. This means you must tell the linker to load every object file in our Tag library that contains category implementation. See for a more complete explanation. Q: Our app uses a tab bar controller, but T ag requires a navigation controller. How do I use a navigation controller with a tab bar controller? A: Integrating a UITabBar with a UINavigationController is described in the ios documentation [ios Library > User Experience > Windows & Views > View Controller Programming Guild for ios > Combined View Controller Interfaces]. Q: I d like to get the T ag Scanner and/or experience viewer to autorotate but we re using a tab bar controller. How can I make this work? A: The Tag library UI components all know how to rotate in any orientation. When you use a tab bar controller, autorotation is turned off by default. It is technically possible to autorotate while using a UITabBarController, for instance using a UITabBarController UITabBarController (Autorotate) - (BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)orientation

15 { UIViewController *controller = self.selectedviewcontroller; if( [controller iskindofclass:[uinavigationcontroller class]] ) { controller = [(UINavigationController *)controller visibleviewcontroller]; } return [controller shouldautorotatetointerfaceorientation:orientation]; Q: My view that launches the T ag scanner or Tag experience gets shifted up or down and the navigation bar looks different. What s wrong? A: When the scanner or experience launches, it sets the navigation bar transparent black on the scan screen and opaque black on the experience. You should restore your preferred settings to the navigation bar on your controller s viewwillappear: method: - (void)viewwillappear:(bool)animated { self.navigationcontroller.navigationbar.barstyle = UIBarStyleDefault; [super viewwillappear:animated]; } Q: Why does my app crash when I launch a tag from my history via TAGLauncher's launchexperiencewithhistoryid:intonavigationcontroller:fordelegate:wi thcontext: method? A: Both of the methods launchexperiencewithhistoryid and launchexperiencewithofflineid take either a historyid or offlineid for the target experience. If you accidentally mix the two (for example, send an offlineid in the historylaunch method), or if you have a corrupted id, the method causes an error. OfflineId and HistoryId are separate IDs that are not interchangable, so be sure you're passing a historyid to the launchexperiencewithhistoryid: method, and offlineid to the offline method. Also, make sure that you pass back the exact history or offline ID we returned to you.

16 This document is provided as-is. Information in this document may change without notice. This document does not provide you with any legal rights to any intellectual property in any Microsoft product. It is disclosed and can be used only pursuant to a valid license agreement with Microsoft to use the Microsoft Tag Scanning SDK. Microsoft and Windows are trademarks of the Microsoft group of companies. All other trademarks are property of their respective owners.