Introduction to Availability

What is Availability?

Skylark's Availability system determines if an object can be viewed by the end-user for all content and metadata within Skylark. This feature is crucial because it allows for effective merchandising, curating, and viewing of content based on extremely granular user characteristics.

Skylark allows multiple availability rules to be applied to an object, and these rules can be named, saved, and reused across objects. Alternatively, a rule can be created specifically for one object.

In this section, you will learn about Skylark's Availability system basics and how to manage an object's availability with the GraphQL API.

Important Factors

An object's availability depends on two factors:

• Time Window: This includes a start and end time during which the object is available.
• Audience: This includes specific details about the user. Typically, an audience is defined by one or more values for every dimension that you have specified.

Skylark is extremely strict with regards to availability. When querying the Skylark API, you must provide one value for every dimension in Skylark. If you do not provide all relevant values then the data will not be returned.

Availability Examples

In Skylark all availability dimensions are strict, meaning the query must be a direct match to the inputted values in order for the availability to be valid.

The below example shows an episode with a single availability entry linked to it. In order to successfully query for that episode you must have the following parameters in your query:

• You must be querying at a time greater than the start date and less than the end date
• You must supply only the operating-system dimension and ios dimension value

If any additional dimensions are supplied the query will return a NotFound.

{
  "title": "Some episode",
  "uid": "c93c7e88-3eca-48ec-9191-a644f93d454e",
  "availability": {
    "objects": [
      {
        "start": "2020-01-01T00:00:00Z",
        "end": "2023-01-01T00:00:00Z",
        "title": "iOS only",
        "dimensions": {
           "objects": [
            {
            	"slug": "operating-system",
              "values": {
                "objects": [
                  {
                    "slug": "ios"
                  }
                ]
              }
         	  }
       	 ]
        }
      }
    ]
  }
}

Successful Query:

query getEpisode {
  getEpisode(
    uid: "93c7e88-3eca-48ec-9191-a644f93d454e", 
    dimensions: [
      {
        dimension: "operating-system",
        value: "ios"
      }
    ], 
    time_travel: "2020-06-01T00:00:00Z"
  ) {
    title
  }
}

Not Found: No dimensions were supplied:

query getEpisode {
  getEpisode(
    uid: "93c7e88-3eca-48ec-9191-a644f93d454e",  
    time_travel: "2020-06-01T00:00:00Z"
  ) {
    title
  }
}

Not Found: Additional non-matching dimensions were supplied:

query getEpisode {
  getEpisode(
    uid: "93c7e88-3eca-48ec-9191-a644f93d454e", 
    dimensions: [
      {
        dimension: "operating-system",
        value: "ios"
      },
      {
        dimension: "device-type",
        value: "smartphone"
      }
    ], 
    time_travel: "2020-06-01T00:00:00Z"
  ) {
    title
  }
}

Not Found: The time is after the end date:

query getEpisode {
  getEpisode(
    uid: "93c7e88-3eca-48ec-9191-a644f93d454e", 
    dimensions: [
      {
        dimension: "operating-system",
        value: "ios"
      }
    ], 
    time_travel: "2023-06-01T00:00:00Z"
  ) {
    title
  }
}

Further Notes

• All dates must be supplied as ISO 8601 date and time, including the timezone, otherwise an error will be thrown.
• If you want to specify any as a value for a dimension, you need to include all values for a given dimension.