Templates#

Templates can be used in Remote Config to define a shape for JSON keys. This enables validation for the data within your game configuration and ensures that any updates made are in the shape that your game client expects.

To define a Template, you create a JSON schema to define the constraints of the data and attach it to one or more keys. Any future updates made against those keys in Remote Config, Game Overrides or the Remote Config API must meet the constraints of the schema defined in the Template.

Templates provide another layer of safety to the live updates made in your game. For example, developers can configure Templates with constraints as part of their initial implementation, and then hand them over to their live operations team to make updates safely.

Getting Started#

To create a Template and add it to an existing Remote Config key, complete the following steps:

1. In the Unity Cloud Dashboard, open Remote Config and select Templates in the sidebar.
2. Select New Template.
3. Enter the schema (using the JSON Schema revision 7 format) for your template into the JSON editor field.
   1. The $id field is required and must be a unique URI. The title field is also required and should be used as a human-readable reference to the Template. The description field is optional and can be used to provide a longer description to your colleagues.
   2. Select Add.
4. Navigate to the Config page and create a new JSON key or edit an existing one.
   1. Select JSON in the Type field.
   2. Select the Template for this key from the Template dropdown.
   3. Select Next.
5. Update the key’s value to ensure it matches the Template.
6. Select Submit to save the key.

Top tip#

You can use an online schema generator (such as JSON to JSON schema) to take an existing key’s JSON and create a new schema as a starting point.

Adding a file to a template#

With an active Cloud Content Delivery subscription, you can include files in Templates and upload them via Remote Config.

To add a file to your Template, add a new property to the definition with type object and subtype file:

...
"properties": {
  "myImage": {
    "type": "object",
    "subtype": "file"
  }
}
...

Once the file field is added and the template is applied to Remote Config keys, you can select a file on your local device to upload to CCD. The CDN link, file name and size are added to the value. You can use the CDN link in your game client to fetch assets at runtime. Files served to the game client count towards your total CCD usage and billing.

For added safety, you can add required fields for your object:

...
"properties": {
  "myImage": {
    "type": "object",
    "subtype": "file",
    "properties": {
      "name": {
        "type": "string"
      },
      "size": {
        "type": "number"
      },
      "url": {
        "type": "string"
      }
    },
    "required": [
      "name",
      "size",
      "url"
    ]
  }
}
...

Use cases#

You can use Templates to achieve various use cases by using the constraints provided by JSON Schema revision 7. The following table provides some example use cases and links to the relevant reference.

Examples#

You can use Templates to define a shape for any change to your game. The following examples provide suggestions to help you get started that you can edit to meet your needs.

Required properties and types for an array of missions#

Below is a schema for a single-level key that configures a number of missions where each must have a name string and a number ID.

{
  "$id": "#missions",
  "title": "Missions",
  "description": "The missions in the game.",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "ID": {
        "type": "number"
      }
    },
    "required": ["name", "ID"]
  }
}

String formatting for in-game messages#

Setting the maximum length for a string, a date format and using a regular expression to check the format of a string.

{
  "$id": "#in-game-inbox",
  "title": "In-Game Inbox",
  "description": "The in-game inbox.",
  "type": "object",
  "properties": {
    "messageID": {
      "type": "number"
    },
    "messageContent": {
      "type": "string",
      "maxLength": 500
    },
    "sendDate": {
      "type": "string",
      "format": "date-time"
    },
    "supportContactNumber": {
      "type": "string",
      "pattern": "^\\+1\\s\\([0-9]{3}\\)\\s[0-9]{3}-[0-9]{4}$"
    }
  },
  "required": ["messageID", "messageContent", "sendDate", "supportContactNumber"]
}

Number formatting for level difficulty#

Setting a minimum and maximum number for a level difficulty field, as well as ensuring it’s always a multiple of 5.

{
  "$id": "#levels",
  "title": "Levels",
  "description": "The levels in the game.",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "levelID": {
        "type": "number"
      },
      "levelName": {
        "type": "string"
      },
      "difficulty": {
        "type": "number",
        "minimum": 0,
        "maximum": 100,
        "multipleOf": 5
      }
    },
    "required": ["levelID", "levelName", "difficulty"]
  }
}

Using an enumerated list for a seasonal event reward#

{
  "$id": "#seasonal-event",
  "title": "Seasonal Event",
  "description": "The seasonal event.",
  "type": "object",
  "properties": {
    "eventID": {
      "type": "number"
    },
    "eventName": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "reward": {
      "type": "string",
      "enum": ["Gold Coins", "Special Item", "Bonus Points", "Exclusive Access"]
    }
  },
  "required": ["eventID", "eventName", "description", "reward"]
}

Conditionally requiring a mission details field when a mission is defined#

This schema ensures that the mission details object is required whenever a mission type is defined - and the same for rewards.

{
  "$id": "#missions",
  "title": "Missions",
  "description": "The missions in the game.",
  "type": "object",
  "properties": {
    "missionType": {
      "type": "string",
      "enum": ["Combat", "Exploration", "Puzzle"]
    },
    "missionDetails": {
      "type": "object"
    },
    "reward": {
      "type": "object",
      "properties": {
        "rewardType": {
          "type": "string",
          "enum": ["Item", "Currency", "Experience"]
        },
        "rewardDetails": {
          "type": "object"
        }
      }
    }
  },
  "dependentRequired": {
    "missionType": ["missionDetails"],
    "rewardType": ["rewardDetails"]
  }
}

Adding an image to a promotional in-game popup#

This schema contains the image file and the related information for an in-game promotional popup.

{
  "$id": "#seasonal-promo",
  "title": "Seasonal Promo",
  "description": "The seasonal promo.",
  "type": "object",
  "properties": {
    "promoID": {
      "type": "number"
    },
    "promoName": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "shopDiscount": {
      "type": "number"
    },
    "promoItemID": {
      "type": "number"
    },
    "popUpImage": {
      "type": "object",
      "subtype": "file"
    }
  },
  "required": ["promoID", "promoName", "shopDiscount", "promoItemID", "popUpImage"]
}