Skip to content

Latest commit

 

History

History
244 lines (205 loc) · 8.37 KB

JSON.md

File metadata and controls

244 lines (205 loc) · 8.37 KB
Raw

JSON File

JSON-format

JSON file in your application has to follow Semantic Versioning and it has to look like this:

{
   "ios":[
      {
         "required_version":"1.2.3",
         "last_version_available":"1.9.0",
         "notify_last_version_frequency":"ALWAYS",
         "requirements":{
            "required_os_version":"8.0.0",
            "region":"hr",
            "bluetooth":"5.0"
         },
         "meta":{
            "key1":"value1",
            "key2":2
         }
      }
   ],
   "macos":[
      {
         "required_version":"10.10.0",
         "last_version_available":"11.0",
         "notify_last_version_frequency":"ALWAYS",
         "requirements":{
            "required_os_version":"10.12.1",
            "region":"hr",
            "bluetooth":"5.0"
         }
      },
   ],
   "meta":{
      "key3":true,
      "key4":"value2"
   }
}

Library will decide which configuration to use based on the platform used and requirements listed under requirements key.

First configuration that meets all the requirements will be used to determine update status.

For more details about requirements, check out this section.

  • Notification frequency

Depending on notify_last_version_frequency property, the user can be notified ONCE or ALWAYS. The library handles this for you. If notification frequency is set to ONCE, in the result values which are returned, the value of updateStatus will be set to UpdateStatus.newUpdateAvailable. Every subsequent call, the library will set the value of updateStatus to UpdateStatus.noUpdateAvailable for that specific version.

  • Metadata

Key-value pairs under "meta" key are optional metadata of which any amount can be sent accompanying the required fields. Metadata can be specified for each configuration and it can also be specified on a global level. In the return values, global metadata and metadata from the appropriate configuration will be merged. If there is not an appropriate configuration, only global metadata will be returned.

Supporting older versions (< 4.0)

To support PrinceOfVersions versions less than 4.0, JSON file will look somewhat different.

JSON still has to follow Semantic Versioning.

  • PrinceOfVersions version < 4.0

    You have to provide an configuration object which conforms older PrinceOfVersions (< 4.0) specification under key ios or macos, depending on a platform.

  • PrinceOfVersions version >= 4.0

    You have to specify configuration described in previous section. Configuration should be stored under key ios2 or macos2.

Described JSON format is displayed below:

{
   "ios":{
      "minimum_version":"1.2.3",
      "minimum_version_min_sdk":"8.0.0",
      "latest_version":{
         "version":"2.4.5",
         "notification_type":"ALWAYS",
         "min_sdk":"12.1.2"
      }
   },
   "ios2":[
      {
         "required_version":"1.2.3",
         "last_version_available":"1.9.0",
         "notify_last_version_frequency":"ALWAYS",
         "requirements":{
            "required_os_version":"8.0.0",
            "region":"hr",
            "bluetooth":"5.0"
         },
         "meta":{
            "key1":"value1",
            "key2":2
         }
      }
   ],
   "macos":{
      "minimum_version":"1.2.3",
      "minimum_version_min_sdk":"10.9.0",
      "latest_version":{
         "version":"2.4.5",
         "notification_type":"ALWAYS",
         "min_sdk":"10.11.0"
      }
   },
   "macos2":[
      {
         "required_version":"10.10.0",
         "last_version_available":"11.0",
         "notify_last_version_frequency":"ALWAYS",
         "requirements":{
            "required_os_version":"10.12.1"
         }
      }
   ],
   "meta":{
      "key3":true,
      "key4":"value2"
   }
}

Requirements

For every configuration, there is a possibility to define requirements. Based on the provided requirements and user-provided requirements checks, the appropriate configuration will be chosen and evaluated for update status.

If you don't provide any requirements for a configuration in JSON, that configuration will be classified as valid.

Defining requirements is possible through requirements array. It is up to you to choose which requirements are necessary for your configuration. However, for setting required operating system version requirement, you can use key required_os_version. By using that key, library will provide requirement check so the user doesn't have to define it. Every other requirement in configuration will be checked with closures provided by the user. Closure can be provided by addRequirement method in PoVRequestOptions class. If requirement closure is not supplied for a given requirement key, library will consider that requirement as not satisfied.

If there is not even one configuration that satisfies all requirements (including required_os_version), library will return error with value requirementsNotSatisfied.

So to sum up, chosen configuration depends on requirements in JSON, requirement checks provided by the user and it's position in configurations array in JSON. For more info, please check example section.

Examples

  • Configurations without requirements
  ...
   "ios":[
      {
         "required_version":"1.2.4",
         "last_version_available":"1.8.0",
         "notify_last_version_frequency":"ALWAYS"
      },
      {
         "required_version":"1.2.3",
         "last_version_available":"1.8.0",
         "notify_last_version_frequency":"ONCE"
      }
   ]
   ...

In this example, first configuration will always be chosen whether or not user provides requirement checks.

  • Configurations with increasing requirements count
{
   "macos":[
      {
         "required_version":"10.10.0",
         "last_version_available":"11.0",
         "notify_last_version_frequency":"ALWAYS",
         "requirements":{
            "required_os_version":"10.12.1"
         }
      },
      {
         "required_version":"9.1",
         "last_version_available":"11.0",
         "notify_last_version_frequency":"ALWAYS",
         "requirements":{
            "required_os_version":"10.11.1",
            "region":"hr",
         }
      },
      {
         "required_version":"9.0",
         "last_version_available":"11.0",
         "notify_last_version_frequency":"ONCE",
         "requirements":{
            "required_os_version":"10.14.2",
            "region":"us",
            "bluetooth":"5.0"
         }
      },
   ]
}

For the sake of this example, let's say that all required OS versions are met. In this example, the first configuration will always be chosen since all requirements are met, second and third configuration won't be evaluated no matter if user defined requirement checks for region or Bluetooth.

  • Configuration with decreasing requirements count
{
   "macos":[
      {
         "required_version":"9.0",
         "last_version_available":"11.0",
         "notify_last_version_frequency":"ONCE",
         "requirements":{
            "required_os_version":"10.14.2",
            "region":"us",
            "bluetooth":"5.0"
         }
      },
      {
         "required_version":"9.1",
         "last_version_available":"11.0",
         "notify_last_version_frequency":"ALWAYS",
         "requirements":{
            "required_os_version":"10.11.1",
            "region":"hr"
         }
      },
      {
         "required_version":"10.10.0",
         "last_version_available":"11.0",
         "notify_last_version_frequency":"ALWAYS",
         "requirements":{
            "required_os_version":"10.12.1"
         }
      }
   ]
}

Here we will also consider required_os_version requirement as met. If user provided requirement checks for both region and Bluetooth and they are both met, first configuration will be chosen. If user provided check only for region, only second and third configuration would be considered, since bluetooth requirement is not met.

Final thoughts

  • You can define requirements in any kind of way that you want and in any sort of order, but be aware that their order profoundly affects the way they are chosen.
  • Best practice would be to put configuration without any requirements (or only with required_os_version requirement) on the bottom of the list since all other configurations after this one will be ignored.

⬅️ Go back