Glossary

SDK (software development kit) - an internal set of development tools that allows professionals to use the standard script for AR scenes in various products. SDK description will be provided in a separate document.

Bundles - a set of files for different operating systems (IOS and Android), providing performance (visual, sound, scenic, etc.) of the whole project in AR. Basic file extensions: * .data, * .scene. 2 bundle groups are provided separately: for Android functionality and for IOS performance.

Markers - files with * .xml and * .dat extensions, which are the Vuforia output data and serve as the basis for AR.

The configuration file - a file called bundles.json with a certain structure, which lists all the components of the project (scenes, content, gui, ardata) and ways to bundles for different countries (if there are several countries, bundles or gui are different for different countries).

Working with the SDK

After the conclusion of the agreement on the inclusion of the project into the Devar platform partners are provided with the platform SDK for adaption of the project. The use of SDK Devar scripts in the project is optional, but if they are not in use, all content should be on the stage, besides the content that is automatically included in the bundles.

Questions about the SDK functionality will be discussed during consultations.

Basic requirements for the project bundles

1. Project bundles should be compiled for Android and iOS platforms separately.

2. Bundles to be compiled on the Unity 2017.4.1.f1 version and the corresponding Vuforia version (currently, Vuforia is built inside Unity, and if it is the correct version, the Vuforia version will also be correct)

3. If there is no Vuforia camera in the book scene, it should be installed (because the SDK works with it). Go to the «World Center Mode» of the Vuforia camera and select First_target mode that allows the scene to move in the camera (the camera of a phone), and to fix objects on a predetermined position in the program.

4. In ImageTarget settings (standard Vuforia object, is added to detect the marker), it is necessary to remove the standard script «Default Trackable Event Handler (Script)» and connect the following from our SDK: Vuforia Image Tracker (Script). All books in the application use the specified script. With Trackable class and its successors, for example, Paintable class, it displays the scene content that matches the recognized marker. Therefore, this class or its certain successor should be used on a mandatory basis in the scene settings.

5. Prescribe the prefab name in the setting of this Trackable script (for the scene content that is linked to the marker). Specify the name In the Bundle Aliases that later will be used in the configuration files (see. p.11). Script successors and their possibilities can be explored in the SDK description.

Pic. 1. Trackable Setting (Script)

6. In the prefab settings you need to specify the folder name (a name identifying this book is, in fact, the name of the project), which will be used both within the bundles and configuration files, as a way to store the corresponding files (see p. 11):

Pic. 2. Specify the storage folder

7. It is necessary to use a specific bundle for each Vuforia marker, which contains all the content prescribed to this marker for the application could load the specific content for this AR marker, but not the whole book. Thus, the scene will include as many ImageTargets as the number of markers used in a book (see Pic. 1).

8. In the standard Vuforia script: Image Target Behaviour (script) - register all the bases and types of markers in a standard way, but with the ability to move the camera without loss of the scene; tick Extended Tracking in Advanced.

9. If a book provides two or more scenes, then the main scene must have a name MainScene. A switching between scenes can be carried out using the SDK SwitchBookScene method (StoreManager.Instance.SwitchBookScene class). A more detailed description of the method can be studied in the SDK guide.

10. The project must have one name (required: capital Latin letters without additional signs except the sign of the underscore), which will be a unique root folder for the project (in the example below - «name_project»), where the bundles for IOS and Android should be placed. This is the same name as specified in p. 6. Structurally, it looks like this:

• android
  • name_project
    • android_bundles
• ios
  • name_project
    • ios_bundles
• anyplatform
  • name_project
    • gui
    • config_file
    • marker_files

11. For each project, you must create your config file - bundles.json, containing all the necessary information on the bundles. Description of bundles.json structure is shown below as a real example bundles.json - «bundles.json». The Devar team members will make the final «bundles.json» file, because it is necessary to assign a number to the book and its locales; adapt it to IOS and Android systems according to the in-team rules; assign the check amount and file sizes (all this take place in semi-automatic mode within the company).

								
  // Here we put scene bundles, which are used in the book.
  "Scenes": [ 
      {
          "Alias": "example_scene", // bundle name
          "File": "example_book / example_scene.scene", // Root bundle / file name on the server.
          "Version": 111, // version
          "Locale": "ru", // add only if the bundle has localization.
      }

          "Alias": "example_scene2", // bundle name
          "File": "example_book / example_scene2.scene", // Root bundle / file name on the server.
          "Version": 111, // version
          "Locale": "ru", // add only if the bundle has localization.
      }
  ]

  // here we put all the bundles of the book.
  "Content": [ 
      {
          "Alias": "example_scene01", // bundle name
          "File": "example_book / example_scene01.data", // Root bundle / file name on the server.
          "Version": 111, // version
          "Locale": "ru", // add only if the bundle has localization.
      }
      {
          "Alias": "example_scene02", // bundle name
          "File": "example_book / example_scene02.data", // Root bundle / file name on the server.
          "Version": 111, // version
          "Locale": "ru", // add only if the bundle has localization.
      }
  ]
  
  // here we add all the images for the book.
  "Gui": {
      "Banner": // Banner. 
          {
              "File": "example_book / gui / banner.jpg", // file name on the server.
              "Version": 1, // version
          }
      "Screenshot_1": // screenshots. 
          [
              {
                  "File": "example_book / gui / screenshot_1_en.jpg", // file name on the server.
                  "Version": 1, // version
                  "Locale": "en" // add only if tied to any particular language.
              }
              {
                  "File": "example_book / gui / screenshot_1_ru.jpg", // file name on the server.
                  "Version": 1, // version
                  "Locale": "ru" // add only if tied to any particular language.
              }
          ]		
      "Screenshot_2": // More screenshots. 
          [
              {
                  "File": "example_book / gui / screenshot_2_en.jpg", // file name on the server.
                  "Version": 1, // version
                  "Locale": "en" // add only if tied to any particular language.
              }
              {
                  "File": "example_book / gui / screenshot_2_ru.jpg", // file name on the server.
                  "Version": 1, // version
                  "Locale": "ru" // add only if tied to any particular language.
              }
          ]
  }
  
  // Here we add the needed Vuforia base markers for the book.
  "Ardata": [ 
      {
          "Alias": "example.dat", // Filename ** dat, Vuforia markers.
          "File": "example_book / example.dat", // The root folder of the book / file name on the server.
          "Version": 111, // version
          "Locale": "ru" // add only if tied to any particular language.
      }
      {
          "Alias": "example.xml", // Filename ** xml, Vuforia markers.
          "File": "example_book / example.xml", // The root folder of the book / file name on the server.
          "Version": 111, // version
          "Locale": "ru" // add only if tied to any particular language.
      }
  ]
								
								

12. The size of the bundle should not exceed 10 MB due to restrictions on the system capacity (the more the size, the longer it downloads), user loyalty (download speed matters) and the requirements of the operating systems, IOS in particular. According to our experience, a file size can be notably reduced by simply removing unused items inside bundles.

Content

1. All content for the scene must be included in bundles, as Trackable script loads scenes content either through bundles or through Resources. However, content uploading from the Resources is extremely undesirable, since in this case, all resources will be loaded into the application itself, which will increase its weight. In this regard, it is necessary to put all content into bundles out of Resources.

2. Textures should have a resolution not more than 1024x1024 pixels;

3. Graphics requirements are consistent with the recommendations laid down in the Unity documentation (https://docs.unity3d.com/Manual/ModelingOptimizedCharacters.html), namely, not more than two or three materials and 15-30 bones on one character, the number of polygons should be in the 3000 to 5000 range for one character.

4. In the project on the canvas (AR scene interface), you must put 2 buttons: reset button that backs to the store (from our SDK - Button_OpenStore class) and the restart button (SDK Button_ReScan class). Standard canvas can be requested from us:

Pic. 3. Standard Devar canvas

Scripts, libraries, plug-ins and shaders

1. All scripts, plug-ins, libraries, and the shaders used in the project must be in the same folder, with all * .meta files, for later inclusion into the main assembly;

2. All scripts must have a unique namespace, to avoid any possible naming coincidence conflicts in classes with other books.

3. Using a Standard shader is not allowed (assigned by default to add materials to the project) in any material used in the project. This is due to the fact that the script weighs more than 5 Mb, which clogs the application and lowers the download speed. This is a standard Unity recommendation for developing mobile applications. In this regard, the shader must be reassigned to another one.

Project design

1. To be added into the platform, a project application must have 4 folders:

·  android – with book bundles for the Android platform (android / example_book)

·  ios - with book bundles for the iOS platform (ios / examlpe_book)

·  anyplatform - added here the following files: bundles.json, Vuforia base (files * .dat and * .xml), gui folder (with the banner and book screenshots for the main interface in the * .jpg format) (anyplatform / example_book)

·  scripts - with all the scripts, shaders, plugins (scripts / example_book). Can be transferred in an archive format.

2. To add visual information on the book / promo you must provide the following information:

·  The list of the countries where the book will be distributed for it to be added into the corresponding showcases;

·  The title of the book in all languages ​​corresponding to the countries in which it is distributed;

·  Description of the book in all languages ​​corresponding to the countries in which it is distributed;

·  Book icon (see the table below with size requirements and restrictions) for each country in which it is distributed (the book cover);

·  Banner for books (see the table below with size requirements and restrictions);

·  At least two screens (see the table below with size requirements and restrictions) for every country in which the book is distributed;

·  If we need to create a new publisher showcase in the platform, we will need a description on all languages of the countries where the book is distributed, as well as the product titles and visual information, according to the table below: