2017.1 DRAFT DOCUMENTATION: This is first draft documentation for a feature that is new in Unity 2017.1 but compatible with Unity 5.5 onwards. As such, the information in this document may be subject to change before final release.

[2017.1] Remote Settings

Use the Unity Analytics Service Remote Settings feature to change values on your Analytics Dashboard which control aspects of your game or application. For example, if you are concerned that some levels in your game might be too hard or too easy, you can create settings that control the difficulty of your level bosses, letting you tune gameplay without releasing an update. 

After you make changes to your Remote Settings, every computer or device starting a new session of your application downloads the new configuration values. No update to the application is necessary. You can connect Remote Settings to individual GameObject properties, or you can read the key-value pairs directly in code and provide your own logic for handling setting changes.

This section describes creating and changing Remote Settings, and using Remote Settings in a Unity Project.

Creating and changing Remote Settings

Before using Remote Settings, you must first enable Unity Services and the Unity Analytics Service for your Unity project. Once you have enabled Analytics, open the Analytics Dashboard and go to the Remote Settings tab to create and change the Remote Settings values. See Using Remote Settings in a Unity project to learn how to access these Remote Settings values in your game or application.

The Analytics Service provides two Remote Settings configurations:

1. The Analytics Service sends Release configuration settings to computers and devices running regular, non-development builds of your application.
2. The Analytics Service sends Development configuration settings to computers and devices running development builds (that is, builds created with the Development Build flag checked on the Build Settings window). Play mode in the Unity Editor counts as a development build.

The Remote Settings tab on the Analytics Dashboard for a game called Raging Bots 

Setting names and value rules

An individual remote setting is a key-value pair. The rules for key names are:

• Key names must be unique within the same configuration.
• Key names must start with a letter.
• Key names may contain only letters and digits.

A setting value can be any of the following primitive types: Int, Float, String, or Bool. The rules for setting values are:

• Int values are 32-bit integers (-2147483648 to 2147483647).
• Float values are single-precision, 32-bit floating-point numbers (about -3.4x1038 to 3.4x1038).
• Strings are limited to 1024 characters.
• You must specify boolean values with the strings “true” or “false”.

Adding, editing, and deleting Remote Settings

To add a Remote Setting:

1. In your Analytics Dashboard, open the Remote Settings tab.
2. Set Configuration to Release or Development for the setting.
3. Enter a name for the key.
4. Set the type for the value.
5. Enter the initial value.
6. Click the Add button.
7. Click the Sync button to publish your changes. (You do not need to click the Sync button after creating each individual setting; you can wait to synchronize your settings until you finish making all changes to the current configuration.)

To edit a Remote Setting:

1. Open the Remote Settings tab in your Analytics Dashboard.
2. Choose the Release or Development Configuration.
3. Click the edit icon  next to the setting you want to change.
4. Make your changes. Note that changing a key name has the same effect as deleting the old key and creating a new one.
5. Click the Save button.
6. Click the Sync button to publish your changes. Unity reads the updated settings the next time players start a session.  

To delete a Remote Setting:

1. Open the Remote Settings tab in your Analytics dashboard.
2. Set Configuration to Release or Development for the setting.
3. Click the delete icon  next to the setting you want to delete.
4. Confirm that you want to delete the setting.
5. Click the Sync button to publish your changes.

Using Remote Settings in a Unity project

To use remote settings in a project, first install the Remote Settings package from the Unity Asset Store. These Assets provide support for viewing your Remote Settings in the Unity Editor, and for mapping Remote Settings values to the fields and properties of components on your GameObjects. See Creating and changing Remote Settings to learn how to define your settings with the Unity Analytics Dashboard.

You can use the Remote Settings component to connect remote settings to the appropriate fields and properties of your GameObjects.

You can also use the [RemoteSettings]() class to write your own script logic for handling Remote Settings.

This section describes how to use Remote Settings in your games and applications:

Remote Settings network requests

Enabling Remote Settings

Managing Remote Settings in the Unity Editor

Remote Settings component

Remote Settings scripting

Testing Remote Settings

Remote Settings network requests

When you create a Remote Settings key-value pair in the Unity Analytics Dashboard, the Unity Analytics Service stores that setting in the Configuration for your project that you have specified (either the Release or the Development configuration). Whenever a player starts a new session of your application, Unity makes a network request for the latest configuration from the Analytics Service. Unity considers a new session to have started when the player launches the application, or returns to an application that has been in the background for at least 30 minutes. Unity requests the Release configuration when running regular, non-development builds of your application, and requests the Development configuration when running development builds. Play mode in the Unity Editor counts as a development build.

Note: For Unity to request the Development configuration, you must build the application with Unity version 5.6.0p4+, 5.6.1p1+, 2017.1+, or Unity 5.5.3p4+, and tick the Development Build checkbox on the Build Settings window. If you build the game with an older version of Unity, Unity always requests the Release configuration.

When the network request for the Remote Settings configuration is complete, the RemoteSettings object dispatches an `Updated` event to any registered event handlers, including those registered by Remote Settings components.  

If the computer or device has no Internet connection and cannot communicate with the Analytics Service, Unity uses the last configuration it received and saved. The `RemoteSettings` object still dispatches an `Updated` event when using a saved configuration. However, if Unity has not saved the settings yet (such as when a player has no network connection the first time they run your game), then the `RemoteSettings` object does not dispatch an `Updated` event, and so does not update your game variables. Requesting the Remote Settings configuration over the network is an asynchronous process that might not complete before your initial Scene has finished loading, or might not complete at all, so you should always initialize your game variables to reasonable defaults.

Note: The web service from which Unity downloads the Remote Settings configuration is read-only, but is not secured. This means that the configuration could be read by third-parties. You should not put sensitive or secret information into your Remote Settings. Similarly, the saved settings file could be read and modified by end-users (although any modifications are overwritten the next time a session starts with an available Internet connection).

Enabling Remote Settings

To enable Remote Settings in a project:

1. If you haven’t already, turn on Unity Analytics for the project.
2. If needed, import the Remote Settings package from the Unity Asset Store.
3. Open the Remote Settings window with Window > Unity Analytics > Remote Settings:
   
   
   
4. Enter the Project Secret Key for your Analytics project and click Next.
   You can find your Project Secret Key on the Unity Analytics Dashboard:

1. On the Analytics Dashboard, click on the  icon, which is located to the right of the Analytics tabs.
   
2. Click the Configure option to open the Project Service Settings page.
3. Locate your Project Secret Key on the page and paste it into the Remote Settings window.
   
   Note that you should keep the Project Secret Key secret. Anyone possessing this value could access your Analytics data. The secret keys for your projects are stored in your Editor preferences file, not in project files.
   
   The Project Secret Key was formerly known as the Raw Data Export API Key. The key value is the same; use the Project Secret Key in any place where you previously used the Raw Data Export API Key.
   

5. On the Remote Settings window, click the Refresh button. The window displays the key-value pairs for any settings you have already created.
   
   If you haven’t created any Remote Settings yet, see Creating and changing Remote Settings to get started.

Managing Remote Settings in the Unity Editor

The Remote Settings window helps you manage your remote settings while you are developing your project in the Editor. (Use the Unity Analytics Dashboard to create and edit the settings themselves.)

The Remote Settings window is not included in the standard Unity download and install. It is part of the Remote Settings Asset package, which is a Unity plug-in. Download the Remote Settings Asset package from the Unity Asset Store and import it into your project.

To open the Remote Settings window, go to Window > Unity Analytics > Remote Settings in the Unity Editor. In order for the Editor to fetch your Remote Settings from the Analytics Service, you must first supply the Project Secret Key as described in Enabling Remote Settings.

The Remote Settings window displays the key-value pairs for the settings defined on your Analytics Dashboard.

The Remote Settings window, part of the Remote Settings plug-in

Click Refresh to fetch the latest remote settings. The Editor also fetches the most recently synchronized settings when you enter Play mode.

Set Active Configuration to Release or Development to choose which set of key-value pairs to work with in the Editor. Note that the Development configuration is always used in Play mode in the Editor. To test the Release configuration, use File > Build and Run, and make sure that the Development Build box is unchecked on the Build Settings window.

Remote Settings component

Use the Remote Settings [component](components) to control the properties of other components in your Scene without writing any code. The Remote Settings component is part of the Remote Settings plug-in, which you can download from the Unity Asset Store.

Before using the Remote Settings component, you must enable Remote Settings in your project and should also create your Remote Settings key-value pairs using the Unity Analytics Dashboard.

You can place the Remote Settings component on the same GameObject as another component you want to control, or place it on a different GameObject. The only requirement is that both the Remote Settings component and any controlled components are active in the same Scene.

Using the Remote Settings component

To connect a remote setting to a component property or field:

1. Go to Window > Unity Analytics > Remote Settings to open the Remote Settings window.
2. Choose the configuration (Release or Development) that contains the setting you are going to connect.
3. Go to the Inspector window for the GameObject that you want to hold the Remote Settings component.
4. Click the Add Component button.
5. Find the Analytics > RemoteSettings script in the list.
   
   
   
6. Click Add Component.

7. To add a new parameter mapping, click the + icon at the bottom of the Remote Setting component’s Parameters list.
8. Drag the GameObject containing the component that you want to remotely control to the parameter’s Object field.

9. Select the property or field you want to control in the parameter’s Field drop-down list.

10. Choose the Remote Setting Key that you want to use to control this component property or field.
    
    
    
11. Click the + icon to add additional parameters.

If no Remote Settings Key names appear in the list, open the Remote Settings window (menu: Window > Unity Analytics > Remote Settings) and click Refresh. If your remote settings are still not displayed in this window, check that you have an Internet connection and that your project is properly set up (see Enabling Remote Settings).

If the wrong keys appear in the list of key names, open the Remote Settings window (menu: Window > Unity Analytics > Remote Settings) and set the Active Configuration to the configuration containing the correct set of keys.

The Remote Settings component cannot set the variables of prefabs that Unity loads later in the Scene than the component itself. Similarly, a Remote Settings component that is loaded later in the Scene can only set variables of objects that are part of the same prefab. Use more than one Remote Settings component to handle these types of situations.

Setting non-primitive properties

You can use the Remote Settings component to set the primitive fields and properties of an object directly. However, to set the variables of an object’s non-primitive members, you do have to write some additional code. The easiest approach is to add primitive-type properties to an object that you can set using the Remote Settings component. Then, implement the setter functions of these properties to update the intended variables of the non-primitive objects.  

Code example

In the example below, the class sets the base color of the Material assigned to a rendered GameObject. To do this, the class defines a primitive string-type property that takes an HTML-style color string. The setter for this property parses the string and sets the Material color accordingly.

```

using UnityEngine;

public class RemoteColorChanger : MonoBehaviour

{

    private string _colorString = "";

    public string ColorString {

        get {

            return _colorString;

        }

        set {

            Color colorObject;

            if (ColorUtility.TryParseHtmlString (value, out colorObject)) {

                _colorString = value;

                Renderer renderer = GetComponent<Renderer> ();

                if (renderer != null) {

                    MaterialPropertyBlock materialProperties = new MaterialPropertyBlock ();

                    renderer.GetPropertyBlock (materialProperties);

                    materialProperties.SetColor ("_Color", colorObject);

                    renderer.SetPropertyBlock (materialProperties);

                }

            } else {

                Debug.LogWarning ("Invalid color string: " + value);

            }

        }

    }

}

```

Using the code example

You can add this `RemoteColorChanger` script to any `GameObject` that has a `Renderer` component. You can then use the Remote Settings component to map a setting key to the `ColorString` property. In this example, the script is a component of a `Cube` object.

A Remote Settings Component mapping the `RemoteColorChanger.ColorString` field to the `ColorString` Remote Setting key

The matching key-value pair on the Remote Settings page of your Analytics Dashboard looks like the following:

The `ColorString` setting as defined on the Analytics Dashboard

Use the same technique to set any non-primitive value.  

Remote Settings scripting

Use the Unity Scripting API RemoteSettings class to handle your settings in code. You can register a handler function for the `RemoteSettings.Updated` event. The `RemoteSettings` class calls all registered handlers whenever a new sessions starts. Create the key-value pairs for the RemoteSettings object to download on the Unity Analytics Dashboard.

Fetching the settings requires a network transaction, so the `RemoteSettings` object dispatches the `Updated` event asynchronously. Your handler function might not be called in the same order on every platform or even on every launch of the same platform. In fact, if no network connection is available and no cached settings are found, the `RemoteSettings` object does not dispatch an `Updated` event at all. Always initialize your configuration variables with reasonable default values, and allow for the possibility that your `Updated` handler can be called at different times or in a different order.

Code example

The following example shows a class that defines a number of properties for tuning game difficulty:

```

using UnityEngine;

public class RemoteTuningVariables : MonoBehaviour {

    public float DefaultSpawnRateFactor = 1.0f;

    public float DefaultEnemySpeedFactor = 1.0f;

    public float DefaultEnemyStrengthFactor = 1.0f;

    public static float SpawnRateFactor{ get; private set; }

    public static float EnemySpeedFactor{ get; private set; }

    public static float EnemyStrengthFactor{ get; private set; }

    void Start () {

        SpawnRateFactor = DefaultSpawnRateFactor;

        EnemySpeedFactor = DefaultEnemySpeedFactor;

        EnemyStrengthFactor = DefaultEnemyStrengthFactor;

        RemoteSettings.Updated +=

            new RemoteSettings.UpdatedEventHandler(HandleRemoteUpdate);

    }

    private void HandleRemoteUpdate(){

        SpawnRateFactor

            = RemoteSettings.GetFloat ("SpawnRateFactor", DefaultSpawnRateFactor);

        EnemySpeedFactor

            = RemoteSettings.GetFloat ("EnemySpeedFactor", DefaultEnemySpeedFactor);

        EnemyStrengthFactor

            = RemoteSettings.GetFloat ("EnemyStrengthFactor", DefaultEnemyStrengthFactor);

    }

} 

```

Notice that the class provides default values in the `RemoteSettings.GetFloat()` method calls. If the `RemoteSettings` object cannot find the specified key (if you misspell a key name, for example), then the method still assigns your default values to the tuning variables. Otherwise, the `GetFloat()` and `GetInt()` methods assign zero to numbers, `GetString()` assigns an empty string to strings, and `GetBool()` assigns false to boolean variables.

The class also assigns the same default values to the properties in the `Start()` method. When Unity cannot access the Analytics Service and no previously cached configuration is available locally, the `RemoteSettings` object does not dispatch the `Updated` event. Assigning the defaults in the `Start()` method ensures that the properties always have reasonable values.

Testing Remote Settings

While you can view the keys and values of both configurations in the Editor, Unity only loads one configuration at runtime. Unity uses the Development configuration in Play mode and in any builds created with the Development Build box checked on the Build Settings window. Unity uses the Release configuration in non-development builds.

Before testing Remote Settings, you must first  create the settings and then either use the Remote Settings component or write the code necessary to map the settings to variables in your game or application.

To test with the Development configuration, click the Play button in the Editor or:

1. Go to File > Build Settings to open the Build Settings window.
2. Check the Development Build box.
3. Click the Build And Run button.

To test with the Release configuration:

4. Go to File > Build Settings to open the Build Settings window.
5. Uncheck the Development Build box.
6. Click the Build And Run button.

* <span class="page-edit">2017-<date> <!-- include IncludeTextNewPageYesEdit --></span>

* <span class="page-edit">2017-<date>  - Service compatible with Unity 5.5 onwards at this date but version compatibility may be subject to change.</span>

* New feature in 2017.1