Remote Config

Overview

Unity Remote Config is a cloud service that allows you to tune your game design without deploying new versions of your application. With Remote Config, you can:

Adapt your game to different types of players. Tune your game difficulty curve in near real time. Alter graphic quality based on device to optimize performance. Roll out new features gradually while monitoring impact. Tailor game settings to different regions or other player segments. Run campaign tests comparing colors, styles, prices, etc. Turn seasonal, holiday, or other time-sensitive events on or off. Enable or disable features for specific player segments or across the entire user base.

Define Rules that control which players receive what settings updates, and when. Unity manages the delivery and assignment of those settings with minimal impact to performance. No update to your application is necessary. When a player launches your game, Remote Config detects contextual attributes used as Rule conditions, based on Unity, the application, the user, or custom criteria that you define. The service then returns customized settings for each player according to the Rules that apply to them. This allows different players using the same version of your game to have slightly different experiences. It also allows you to understand the impact each experience has on your business.

Authentication

The Remote Config web APIs require authentication via Unity's APIs. To authenticate with Unity, use a Unity account with permission to access the appropriate Organization and Project (manage accounts and roles in the developer dashboard). In the POST payload below, replace [username] and [password] with your Unity account login information.

curl --header "Content-Type: application/json" --request POST --data '{"username":"[username]","password":"[password]","grant_type":"PASSWORD"}' https://api.unity.com/v1/core/api/login

The response contains an access token similar to the example shown below. Use the token when calling the Gateway APIs. The response also returns an expires_in timestamp; if the token expires, repeat the step above to get a new one.

{
  "access_token" : access_token,
  "refresh_token" : ...,
  "expires_in" : ...
}

Use the token as the Authorization header with "Bearer: [access_token]", in order to successfully authenticate and use the Remote Config REST API.

access_token

Genesis access_token returned from the above curl request

Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "Token"

Environments

View remote config environments

Get Environments

Returns the list of environments for a Project. Remote Config will create ‘Development’ and ‘Release’ environments for your Project if none exist. Currently, these are the only two environments supported.

Authorizations:
query Parameters
projectId
required
string

Genesis projectId

Responses

200

successful operation

403

Forbidden

get environments?project={projectId}
https://remote-config-api.uca.cloud.unity3d.com/environments?project={projectId}

Request samples

Copy
curl -X GET \
https://remote-config-api.uca.cloud.unity3d.com/environments?projectId={projectId} \
  -H 'Authorization: Bearer <genesis_access_token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "environments":
    [
    ]
}

Configs

Interact with configs to store settings. A Setting is a key that you’ll map to a parameter in your game code, so you can dynamically change its value without changing your code.

Create Config

Create a Config for a given environment

Authorizations:
query Parameters
projectId
required
any

Genesis projectId

Request Body schema: application/json

Created user object

environmentId
required
string <uuid>
type
required
string
Value:"settings"

We currently only support one config type (more to come).

value
required
Array of StringSetting (object) or IntSetting (object) or BoolSetting (object) or FloatSetting (object) (Setting)

Array of Setting objects that represent the default values in your game.

Responses

200

successful operation

400

Bad Request

403

Forbidden

post environments/{environmentId}/configs?projectId={projectId}
https://remote-config-api.uca.cloud.unity3d.com/environments/{environmentId}/configs?projectId={projectId}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "environmentId": "string",
  • "type": "settings",
  • "value":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "createdAt": "2019-08-13T18:12:14Z"
}

Get Config

Returns Config for a given ID

Authorizations:
query Parameters
projectId
required
string

Genesis projectId

Responses

200

successful operation

403

Forbidden

get configs/{configId}?projectId={projectId}
https://remote-config-api.uca.cloud.unity3d.com/configs/{configId}?projectId={projectId}

Request samples

Copy
curl -X GET \
https://remote-config-api.uca.cloud.unity3d.com/configs/{configId}?projectId={projectId} \
  -H 'Authorization: Bearer <genesis_access_token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "projectId": "string",
  • "environmentId": "string",
  • "type": "settings",
  • "value":
    [
    ],
  • "createdAt": "2019-08-13T18:12:14Z",
  • "updatedAt": "2019-08-13T18:12:14Z"
}

Update Config

Updates the value of an existing Config

Authorizations:
query Parameters
projectId
required
string

Genesis projectId

Request Body schema: application/json

Config object

environmentId
required
string <uuid>
type
required
string
Value:"settings"

We currently only support one config type (more to come).

value
required
Array of StringSetting (object) or IntSetting (object) or BoolSetting (object) or FloatSetting (object) (Setting)

Array of Setting objects that represent the default values in your game.

Responses

204

No Content

400

Bad Request

403

Forbidden

put configs/{configId}?projectId={projectId}
https://remote-config-api.uca.cloud.unity3d.com/configs/{configId}?projectId={projectId}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "environmentId": "string",
  • "type": "settings",
  • "value":
    [
    ]
}

Delete Config

Deletes an existing Config

Authorizations:
query Parameters
projectId
required
any

Genesis projectId

Responses

204

No Content

403

Forbidden

delete configs/{configId}?projectId={projectId}
https://remote-config-api.uca.cloud.unity3d.com/configs/{configId}?projectId={projectId}

Request samples

Copy
curl -X DELETE \
https://remote-config-api.uca.cloud.unity3d.com/configs/{configId}?projectId={projectId} \
  -H 'Authorization: Bearer <genesis_access_token>'

Get Configs by Environment ID

Returns the list of all configs for a Environment. Currently, the only supported config type is "settings"

Authorizations:
query Parameters
projectId
required
string

Genesis projectId

Responses

200

successful operation

403

Forbidden

get environments/{environmentId}/configs?project={projectId}
https://remote-config-api.uca.cloud.unity3d.com/environments/{environmentId}/configs?project={projectId}

Request samples

Copy
curl -X GET \
https://remote-config-api.uca.cloud.unity3d.com/environments/{environmentId}/configs?projectId={projectId} \
  -H 'Authorization: Bearer <genesis_access_token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "configs":
    [
    ]
}

Rules

Remote Config uses Rules to target specific user groups and deliver different settings for each group. Rules are linked to Settings, which you’ll map to variables in your game code and override their default values when the audience criteria for a Rule is met.

Important: Each environment has a unique Rules set

Create Rule

Create a Rule for a given Config

Authorizations:
query Parameters
projectId
required
any

Genesis projectId

configId
required
any

Config Id

Request Body schema: application/json

Created rule object

environmentId
required
string <uuid>
configId
required
string <uuid>
name
required
string

The name for your Rule

condition
required
string

The Condition is a JEXL expression of contextual data attributes used to define the audience for which you want a Rule to apply.

JEXL Support

  • JexlExpression from the Java Expression Language (JEXL) spec.
  • JexlScripts are not supported.

Categories

Remote Config currently supports three attribute categories.

Category Description
user Custom developer-defined attributes that describe the user
app Custom developer-defined attributes that describe the application
unity Predefined attributes (detailed below)

Predefined unity attributes

Attribute Type Description Example
appBuildVersion String The build number your application is running "1"
appVersion String The version your application is running "1.0"
cpu String The name of the cpu processor "Intel(R) Core(TM) i7-7920HQ CPU @ 3.10GHz"
cpuFrequency Int The processor frequency in MHz of the device running your app 3100
country String The applicable country. This attribute uses ISO 3166-1 alpha2 country codes "US"
language String The applicable language. This attribute uses ISO 639-1 language codes "en"
osVersion String The operating system version of the device running your app "Mac OS X 10.14.3"
platform String The applicable device or platform (see below) "iOS"
timeSinceStart Int The time in milliseconds since a session of your app has begun 2473741
graphicsDeviceVendor String Vendor of the user's graphics card "ATI Technologies Inc."
ram Int Amount of ram memory in MB on the device 16384

Supported platforms

  • Android
  • iOS
  • Linux
  • macOS
  • Metro
  • SamsungTV
  • Switch
  • Tizen
  • tvOS
  • WebGL
  • Wii
  • Windows
value
required
Array of RuleStringSetting (object) or RuleIntSetting (object) or RuleBoolSetting (object) or RuleFloatSetting (object) (RuleSetting)
enabled
boolean
Default: false
rolloutPercentage
integer [ 0 .. 100 ]
Default: 100

The percentage of your user base that will adhere to this rule. For values less than 100, Unity randomly assigns the Rule to that percent of your players on a user ID basis. While experiences may differ from player to player, players will have a consistent experience each session.

priority
integer [ 0 .. 1000 ]
Default: 1000

Integer between 0 (highest priority) and 1000 (lowest priority). In the event of a conflict, priority is awarded to the Rule that was created first.

startDate
string <date-time>
Default: null

Timestamp in ISO 8601 UTC format (YYYY-MM-DDThh:mm:ssZ). Lower bound for when enabled rules will go into effect.

endDate
string <date-time>
Default: null

Timestamp in ISO 8601 UTC format (YYYY-MM-DDThh:mm:ssZ). Upper bound for when enabled rules will cease to be active.

Responses

200

successful operation

400

Bad Request

403

Forbidden

post rules?projectId={projectId}
https://remote-config-api.uca.cloud.unity3d.com/rules?projectId={projectId}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "environmentId": "string",
  • "configId": "string",
  • "name": "string",
  • "condition": "string",
  • "value":
    [
    ],
  • "enabled": false,
  • "rolloutPercentage": 100,
  • "priority": 1000,
  • "startDate": "2019-08-09T17:13:56.000Z",
  • "endDate": "2020-08-09T17:13:56.000Z"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": null,
  • "createdAt": null
}

Get Rule

Returns Rule for a given ID

Authorizations:
query Parameters
projectId
required
string

Genesis projectId

Responses

200

successful operation

403

Forbidden

get rules/{ruleId}?projectId={projectId}
https://remote-config-api.uca.cloud.unity3d.com/rules/{ruleId}?projectId={projectId}

Request samples

Copy
curl -X GET \
https://remote-config-api.uca.cloud.unity3d.com/rules/{ruleId}?projectId={projectId} \
  -H 'Authorization: Bearer <genesis_access_token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "projectId": "string",
  • "environmentId": "string",
  • "configId": "string",
  • "name": "string",
  • "condition": "string",
  • "value":
    [
    ],
  • "enabled": false,
  • "rolloutPercentage": 100,
  • "priority": 1000,
  • "startDate": "2019-08-09T17:13:56.000Z",
  • "endDate": "2020-08-09T17:13:56.000Z",
  • "createdAt": "2019-08-13T18:12:15Z",
  • "updatedAt": "2019-08-13T18:12:15Z"
}

Update Rule

Updates an existing rule

Authorizations:
query Parameters
projectId
required
any

Genesis projectId

Request Body schema: application/json

Config object

environmentId
required
string <uuid>
configId
required
string <uuid>
name
required
string

The name for your Rule

condition
required
string

The Condition is a JEXL expression of contextual data attributes used to define the audience for which you want a Rule to apply.

JEXL Support

  • JexlExpression from the Java Expression Language (JEXL) spec.
  • JexlScripts are not supported.

Categories

Remote Config currently supports three attribute categories.

Category Description
user Custom developer-defined attributes that describe the user
app Custom developer-defined attributes that describe the application
unity Predefined attributes (detailed below)

Predefined unity attributes

Attribute Type Description Example
appBuildVersion String The build number your application is running "1"
appVersion String The version your application is running "1.0"
cpu String The name of the cpu processor "Intel(R) Core(TM) i7-7920HQ CPU @ 3.10GHz"
cpuFrequency Int The processor frequency in MHz of the device running your app 3100
country String The applicable country. This attribute uses ISO 3166-1 alpha2 country codes "US"
language String The applicable language. This attribute uses ISO 639-1 language codes "en"
osVersion String The operating system version of the device running your app "Mac OS X 10.14.3"
platform String The applicable device or platform (see below) "iOS"
timeSinceStart Int The time in milliseconds since a session of your app has begun 2473741
graphicsDeviceVendor String Vendor of the user's graphics card "ATI Technologies Inc."
ram Int Amount of ram memory in MB on the device 16384

Supported platforms

  • Android
  • iOS
  • Linux
  • macOS
  • Metro
  • SamsungTV
  • Switch
  • Tizen
  • tvOS
  • WebGL
  • Wii
  • Windows
value
required
Array of RuleStringSetting (object) or RuleIntSetting (object) or RuleBoolSetting (object) or RuleFloatSetting (object) (RuleSetting)
enabled
boolean
Default: false
rolloutPercentage
integer [ 0 .. 100 ]
Default: 100

The percentage of your user base that will adhere to this rule. For values less than 100, Unity randomly assigns the Rule to that percent of your players on a user ID basis. While experiences may differ from player to player, players will have a consistent experience each session.

priority
integer [ 0 .. 1000 ]
Default: 1000

Integer between 0 (highest priority) and 1000 (lowest priority). In the event of a conflict, priority is awarded to the Rule that was created first.

startDate
string <date-time>
Default: null

Timestamp in ISO 8601 UTC format (YYYY-MM-DDThh:mm:ssZ). Lower bound for when enabled rules will go into effect.

endDate
string <date-time>
Default: null

Timestamp in ISO 8601 UTC format (YYYY-MM-DDThh:mm:ssZ). Upper bound for when enabled rules will cease to be active.

Responses

200

successful operation

403

Forbidden

put rules/{ruleId}?projectId={projectId}
https://remote-config-api.uca.cloud.unity3d.com/rules/{ruleId}?projectId={projectId}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "environmentId": "string",
  • "configId": "string",
  • "name": "string",
  • "condition": "string",
  • "value":
    [
    ],
  • "enabled": false,
  • "rolloutPercentage": 100,
  • "priority": 1000,
  • "startDate": "2019-08-09T17:13:56.000Z",
  • "endDate": "2020-08-09T17:13:56.000Z"
}

Delete Rule

Deletes existing rule

Authorizations:
query Parameters
projectId
required
any

Genesis projectId

Responses

200

successful operation

403

Forbidden

404

Rule Not Found

delete rules/{ruleId}?projectId={projectId}
https://remote-config-api.uca.cloud.unity3d.com/rules/{ruleId}?projectId={projectId}

Request samples

Copy
curl -X DELETE \
https://remote-config-api.uca.cloud.unity3d.com/rule/{ruleId} \
  -H 'Authorization: Bearer <genesis_access_token>'

Get Rules by Config ID

Returns the list of Rules for a Config.

Authorizations:
query Parameters
projectId
required
string

Genesis projectId

Responses

200

successful operation

403

Forbidden

get configs/{configId}/rules?projectId={projectId}
https://remote-config-api.uca.cloud.unity3d.com/configs/{configId}/rules?projectId={projectId}

Request samples

Copy
curl -X GET \
https://remote-config-api.uca.cloud.unity3d.com/configs/{configId}/rules?projects={projectId} \
  -H 'Authorization: Bearer <genesis_access_token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "rules":
    [
    ]
}

Reports

Generate a report to see raw or aggregate user assignment events

Create Report

Generate a Report of your user assignment events. Currently 2 Types of Reports are supported (declared as reportingType value in request body):

  1. "summary" = Raw User Assignment Data Report
  2. "aggregate" = Aggregated User Assignment Report (includes unique count of users by Rule)
Authorizations:
query Parameters
projectId
required
any

Genesis projectId

Request Body schema: application/json

Created user object

dateRange
required
object
reportType
required
string
Enum:"summary" "aggregate"

Responses

200

successful operation

400

Bad Request

403

Forbidden

post reports?projectId={projectId}
https://remote-config-api.uca.cloud.unity3d.com/reports?projectId={projectId}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "dateRange":
    {
    },
  • "reportType": "summary"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "createdAt": "2019-08-13T18:12:15Z",
  • "status": "success"
}

Get Reports

Returns all Reports for a given project

Authorizations:
query Parameters
projectId
required
string

Genesis projectId

Responses

200

successful operation

403

Forbidden

get reports?projectId={projectId}
https://remote-config-api.uca.cloud.unity3d.com/reports?projectId={projectId}

Request samples

Copy
curl -X GET \
https://remote-config-api.uca.cloud.unity3d.com/reports?projectId={projectId} \
  -H 'Authorization: Bearer <genesis_access_token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "job":
    [
    ]
}

Get Report

Check the status of a report, if the status is a success, response includes a gcsUrl to download report csv.

Authorizations:
query Parameters
projectId
required
string

Genesis projectId

Responses

200

successful operation

403

Forbidden

get reports/{reportId}?projectId={projectId}
https://remote-config-api.uca.cloud.unity3d.com/reports/{reportId}?projectId={projectId}

Request samples

Copy
curl -X GET \
https://remote-config-api.uca.cloud.unity3d.com/reports/{reportId}?projectId={projectId} \
  -H 'Authorization: Bearer <genesis_access_token>'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "jobId": null,
  • "status": "string",
  • "resourceUrls":
    [
    ],
  • "createdAt": null
}