When using the Headjack SDK for Unity, you can create a wide variety of apps. As long as your use case is to show video content, the Headjack SDK can help. And with the variety of existing Headjack app templates available for download as a Unity project, you can hit the ground running. This article will dive into how to start customizing an existing app template, how to set up custom variables to change your app on-the-fly within the Headjack CMS and how to integrate with our other solutions, like Headjack Operator for remote control.

Getting Started with a Custom Template

To get started, it is highly recommended to download one of our templates from the Headjack Template Marketplace. This ensures that you start with a correctly configured Unity 2021.3 project, including third-party (VR) SDKs and platform-specific settings. Additionally, the template can serve as a good starting point for the app’s menus and flow, as well as providing a great example of how to implement the fundamental functionality of your app like input, video playback or remote control.

Downloading a Headjack template as a Unity project is as simple as picking the right template for your use case from the Template Marketplace and clicking the “Generate Unity package” link on the right of the template details page.

If you are building a VR app, we would recommend starting with the Essential All-In-One template. It is kept up-to-date with the latest VR developments and hardware and can be easily adjusted to work like the similar Essential Grid, Essential Kiosk or Essential Cinema templates. 

If instead you are building your app for smartphones, please have a look at the Essential Mobile template. This template includes a great flat menu for phones and works great with standard/flat video, while also fully supporting immersive video formats.
To set up and preview your newly downloaded template in Unity, please refer to this dedicated setup guide. Now that you have a configured Unity project, changes like colors, fonts or even new functionality are done like any other development in Unity, which you can learn more about in the Unity manual or by checking out the Headjack SDK scripting reference.

Custom Variables

Custom variables or template variables are a particularly versatile way to customize your app and add functionality. After setting up custom variables in both the Headjack web interface and in your Unity project, you can make changes to your app or add new files to every project in your app right from the Headjack web interface. And those changes are immediately live in the app, even if your app is already installed on different devices.

To demonstrate custom variables, in this example we will be adding a second thumbnail image to every project in the app, to show in a custom template menu.

Step 1

If you haven’t already, create a new template in Headjack that will become your custom template in the Headjack CMS.

NOTE: You may upload a temporary/empty .zip template package if you are still developing your template.

Step 2

At the bottom of the template edit page, add a new variable.

The variable type you choose determines what kind of input is accepted:

  • String: text input field
  • Dropdown: select one of several predefined options
  • Multi-select: select one or more options from a predefined list
  • Date/time: select a particular date and time
  • Colorpicker: select a color
  • File upload: select or upload a file of a predefined type/extension

Ticking the “Variable per project” checkbox ensures that a different value can be set for every project in the app, otherwise only a single value can be set for the entire app.

Remember the (auto-generated) “Name” field, as that is the identifier you will use in your Unity script to access the value of this custom variable.

For this example we will fill in the following:

Step 3

Navigate to the app edit page of the app you have configured to use in Unity and switch its template to the new custom template:

Step 4

Now when you edit or add projects in this app, you can navigate to the “Extra settings” tab at the bottom of the project edit dialog and you’ll find the custom variable you just created, ready to be filled in for that particular project.

Custom variables that do not have the “Variable per project” checkbox set can be edited in the template “Settings” menu on the right of the app edit page:

Step 5

You can start retrieving the value(s) of the new custom variable in Unity. Find the call to Headjack.App.Initialize() in your codebase. After this initialization of the Headjack app metadata, you can start getting the custom variable value(s). So in the OnReady callback use Headjack.CustomVariables.GetVariable():

Headjack.App.Initialize(
    (bool initSuccess, string initError) => {
      if (initSuccess) {
        string secondThumb = Headjack.CustomVariables.GetVariable<string>(
            "second_project_thumbnail",
            Headjack.App.GetProjects()[0]);
        Debug.Log("Media ID of additional thumbnail of first project: " +
                  secondThumb);
      }
    });

You’ll notice that the value of the file upload variable is returned as a media ID string, which can then be used to download the file (Headjack.App.DownloadSingleMedia()) and load the file in the case of images (Headjack.App.GetImage()).

Other custom variable types return the value as:

  • String: string containing the text
  • Dropdown: string of option selected from dropdown
  • Multi-select: string[] of all selected options (can be empty array)
  • Date/time: System.DateTime object containing the selected date & time
  • Colorpicker: UnityEngine.Color object containing the selected color
  • File upload: string of media ID to pass to other functions for downloading, etc.

As you can see, with these custom variables it is possible to greatly expand the functionality of the Headjack CMS by allowing the template developer to add additional options to the app that can be changed live, as the new value(s) are retrieved from the Headjack servers every time the app is initialized.

You may wonder if you can use the Headjack Link app with your new custom template, to allow others to log into your app and view your template with the 6-digit app pin code. Unfortunately, due to app store restrictions it is not possible to support custom templates in the Headjack Link app. The only templates currently supported in the Headjack Link app are the main “Essentials” templates (All-in-one, Grid, Kiosk and Cinema).

However, you can include the Link pin code login system into your own custom app, for instance to brand it and send all your clients the same app that allows them to log in to view their own content. Please contact us and describe how you’re planning to use the Link login system and we can provide you with private access to the Unity project of the Headjack Link app.

Similarly, if you have a custom use case for the Headjack Operator remote control system and want to develop a custom version of that tablet app, please contact us to get private access to the full Unity project of the Headjack Operator app.

But you don’t need the Operator Unity project to make your custom app template support remote control using the existing Headjack Operator app on the app stores. All you need is to follow the good example of the Essential Cinema template. Download that template and look through the Assets/Template/Scripts/CinemaHandler.cs source code. That well documented class has examples of every common use of the Operator remote control system. More information is in the documentation of the Headjack.Cinema.LocalClient class.