Version: 2017.2
Remote Settings
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
The Remote Settings tab on the Analytics Dashboard for a game called Raging Bots

Each Remote Setting consists of a key, a default value, and, optionally, segmented values. When a setting contains segmented values, the segments that the current player is in determine which values are included in the configuration. If more than one segment applies, the configuration includes the value from the highest priority segment.

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, digits, and the characters: “.”, “_”, and “-”.

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 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. Click ADD NEW KEY-VALUE (at the top of the settings list).

  4. Enter a name for the key.

  5. Set the type for the value.

  6. Enter the default value.

  7. Click the Save button.

  8. 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.)

Note: To add values targeted to different segments, save the default key-value setting and then edit it. The segment options only appear when you edit a setting, not when you first create one.

Editing Remote Settings

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.

Resolving simultaneous edits

If two people on your team edit the Remote Settings on a project at the same time, you can get a conflict when trying to synchronize the modified settings with the service.

Warning that someone else has changed the settings while you were editing the same project
Warning that someone else has changed the settings while you were editing the same project

When a conflict occurs, you have the following options:

OVERWRITE

Discards all changes on the service since you last synced and pushes your settings to the service. When you choose overwrite, the settings on the service will match your current settings exactly.

MERGE

Combines your current settings with the modified settings from the service and gives you the opportunity to make changes before completing the synchronization operation.

If you edit the same setting value, your changes overwrite the version from the service. In addition, values and settings deleted on the service are restored (since they still exist in your version). Otherwise, changes from the service since you last synced are retained.

After merging, your Remote Settings page is updated to reflect the merger, but the combined settings are not pushed to the server. You can review the updated changes and click the Sync button again when you are ready.

CANCEL

Cancels the synchronization operation and closes the conflict dialog without making any changes. Your settings are not saved to the service.

Adding different values for different segments

You can assign multiple segmented values to a single Remote Settings key. When a player is a member one of the segments for which a specific value exists, Unity sends that value to the player instead of the default, All Users value. (If a player qualifies for several segmented values, Unity sends the value from the highest priority segment.)

To set a value specific to a given segment:

  1. Open the Remote Settings tab in your Analytics Dashboard.

  2. Choose the Release or Development Configuration.

  3. Add the Remote Setting if it does not already exist.

  4. Click the edit icon at the far right of the setting.

  5. Click ADD EXISTING SEGMENT.

  6. In the new row, choose the segment from the drop-down list and enter a value.

  7. Click the Save button.

Deleting Remote Settings

To delete a Remote Setting, first open the edit view for the setting:

  1. Open the Remote Settings tab in your Analytics dashboard.

  2. Set Configuration to Release or Development for the setting.

  3. Click the edit icon next to the setting you want to delete to open the edit view:

  4. To delete a value for a particular segment, click the minus button to the right of the edit view and then click Save. (You cannot delete the default All Users value.)

  5. To delete the entire setting, click the delete icon at the bottom of the edit view and then confirm you want to delete the setting.

  6. Click the Sync button to publish your changes.

Setting segment priority

When a player is a member of more than one segment, Unity sends the value assigned for highest priority segment. (If a setting doesn’t have any segmented values, or the player isn’t a member of the segments that do have different values for a key, then Unity sends the All Users value.) You can set the order of your segments to specify which segmented values should take precedence when there is an overlap.

To set the segment priority:

  1. Open the Remote Settings tab in your Analytics dashboard.

  2. Choose the Release or Development Configuration.

  3. Click the segment priority icon.

  4. The Segment Priority window opens, showing your current order. Only segments already assigned values for any Remote Settings apear in the window.

  5. Reorder the segments by clicking and dragging the items into place.

  6. When the order is correct, click Save.

  7. Click the Sync button to publish your changes.

The segment priority applies to all settings within a configuration, but you can have a different priority for the Development and Release configurations.


  • 2017–08–28 Page amended with no editorial review

  • 2017–08–28 - Service compatible with Unity 5.5 onwards at this date but version compatibility may be subject to change.

  • 2017–06–30 - Added: Allow the characters “.”, “_”, and “-” in key names.

  • New feature in 2017.1

  • 2017–08–28 - Added segmented Remote Settings: set different values for different segments in 2017.1

Remote Settings
Using Remote Settings in a Unity project