Skip to content

Communication with the H5P Hub

Jump to bottom
Sebastian Rettig edited this page Sep 4, 2019 · 1 revision

Context

When the H5P hub is called in the PHP implementation it updates something called the "Content Type Cache". This cache is persisted in the database (through the plugin) and contains the information retrieved from the Hub, so that the Hub isn't called every time a user opens the editor. The term "Content Type Cache" confusingly is also used for the data structure that contains the cached hub data and further information about locally installed libraries.

Updating the Content Type Cache

The update of the content type cache has to be called regularly, e.g. through a cronjob.

Steps:

  1. Register at the H5P hub, if not done before (to get uuid of the site)
  2. Compile usage statistics if option is set
  3. fetch content types from Hub (by sending info about the running site, including usage statistics, all in one combined object)
  4. Update the cache

Registration process

POST https://api.h5p.org/v1/sites with following as params:

{
    uuid: string, // can be '' to register
    platform_name: string, // "test"
    platform_version: string, // "1.0"
    h5p_version: string, // "1.22"
    disabled: number, // 1 or 0 ("fetching disabled", unclear what this does)
    local_id: number, // crc32 hash of full plugin path used as id
    type: string // type of network the site is running in (can be: local, network, internet)
    core_api_version: string // "1.19"
}

returns JSON object:

{
    uuid: string // the newly assigned uuid of your site, store this object in the future
}

Compiling Usage Statistics

Compile object with:

{
  num_authors: numbers, // number of active authors
  libraries: {
    'H5P.XXX 1.5': {
      patch: number, // used patch version
      content: number, // number of instances created for this library
      loaded: number, // number of 'loaded' events (= views?) from log
      created: number, // number of 'created' events from log
      createdUpload: number, // number of 'createdUpload' events from log
      deleted: number, // number of 'deleted' events from log
      resultViews: number, // number of 'resultViews' events from log
      shortcodeInserts: number // number of 'shortcode insert' events from log
    }
  }
}

Fetching hub data

POST https://api.h5p.org/v1/content-types/ with combination of registration data and usage statistics (everything in one single object) in body (x-www-form-url-encoded). The call returns a JSON file with library information (could be empty).

Storing content type cache

The received data can be for example stored in a database table:

    left: column name; right: property in JSON got from H5P hub
    machine_name: id,
    major_version: version->major,
    minor_version: version->minor,
    patch_version: version->patch,
    h5p_major_version: coreApiVersionNeeded->major,
    h5p_minor_version: coreApiVersionNeeded->minor,
    title: title,
    summary: summary,
    description: description,
    icon : icon,
    created_at: createdAt (format?),
    updated_at: updatedAt (format?),
    is_recommended: isRecommended (boolean),
    popularity: popularity,
    screenshots: screenshots (as JSON text),
    license: license (as JSON text or empty array),
    example: example,
    tutorial: tutorial (or empty text),
    keywords: keywords (as JSON text or empty array),
    categories: categories (as JSON text or empty array),
    owner: owner

Adding further information to report back to the user

The H5P server doesn't just return the data it got from the H5P Hub, but adds more information:

Add the following to the output:

    {
      outdated: boolean, // true: The cache is outdated and not able to update
      libraries: ..., // all libraries that are currently available to the user (= what you received from the H5P hub)
      user: string, // (can be "local" or "external")
      recentlyUsed: [], // machine names of most recently used libraries of the active user (first most recently used)
      apiVersion: { major: number, minor: number },
      details: // info messages can be null
    }

Adding local libraries to the content cache

When creating new content, users should also see content types in the list that were added manually, they should be able to see what content types can be updated by fetching a new version from the hub etc. For this you have to add information about locally installed libraries to the content type cache:

  1. get latest library versions (only those marked as runnable)

    • return { id, machineName, title, majorVersion, minorVersion, patchVersion, hasIcon, restricted }[]

  2. create a user specific content type cache

    • get full content type cache (the data you received from the H5P hub)
    • set restricted property if necessary (restricted content types can only be used by special users
    • convert cache data of each library to JSON these properties
      { 
        'id'
        'machineName'
        'majorVersion'
        'minorVersion'
        'patchVersion'
        'h5pMajorVersion'
        'h5pMinorVersion'
        'title'
        'summary'
        'description'
        'icon'
        'createdAt'
        'updatedAt'
        'isRecommended'
        'popularity'
        'screenshots'
        'license'
        'owner'
        
        'installed': false,
        'isUpToDate': false,
        'restricted': boolean,
        'canInstall': boolean,

        // the following properties should only be added if they are not empty
        'categories'?
        'keywords'?
        'tutorial'?
        'example'?
      }

  1. Merge the hub data with the data from local libraries in the PHP implementation see: h5peditor.class.php->mergeLocalLibsIntoCachedLibs

    • go through all local libraries: add local libraries to supplement content type cache (just add to existing structure passed to the function)
      • set icon path (typically icon.svg)
      • go through all cached libraries
        • if cached library information is identical to local library:
          • lib.installed = true
          • lib.restricted = ...
          • lib.localMajorVersion = ...
          • lib.localMinorVersion = ...
          • lib.localPatchVersion = ...
          • if local lib is newer or same as cache:
            • lib.isUpToDate = true
      • If a library is only installed locally and not present in the hub, add minimal data for it:
      {
          'id': number,
          'machineName': string,
          'title': string,
          'description': string,
          'majorVersion': number,
          'minorVersion': number,
          'patchVersion': number,
          'localMajorVersion': number, // same as majorVersion
          'localMinorVersion': number, // same as minorVersion
          'localPatchVersion': number, // same as patchVersion
          'canInstall': false,
          'installed': true,
          'isUpToDate': true,
          'owner': '',
          'restricted': boolean, // depending on what is set in the local database
          'icon': string // path to icon.svg
      }

- set H5P.Questionnaire and H5P.FreeTextQuestion to restricted if setting enable_lrs_content_types is false
Clone this wiki locally