Skip to main content

Implementing contributions

Not Released

PlayMakers is not currently released for productive usage. The material below is a preview reference.

Please contact us to get started.

Manual implementation​

Through the Studio Dashboard, it is possible to download submissions individually, or as an archive batch. The integration into the product is then a manual step, and no prior work is needed to add the contribution. This is however an asynchronous method that doesn't scale well and requires constant work.

tip

The recommended approach is one of the automated implementations below.

Automated implementation​

Frequency​

Regular updates​

In case the product distributes daily, weekly, or any other periodicity, updates, it is relevant to script the download of all new submissions and bundle them within each release.

Real-time​

If the product has internet access, it is possible to allow the client to download new submissions immediately as they come:

  • at launch: by starting a background process to update all the latest contributions
  • on the go: polling every now and then, to check if there are novelties and grabbing them

Method​

Relevant API Endpoints​

To implement automated contributions effectively, you can utilize the following API endpoints to manage submissions. The key endpoint for retrieving submissions is designed to allow you to filter by user ID, project ID, and submission state.

Get All Submissions by Project ID​

This endpoint allows you to fetch all submissions associated with your specefic project.

  • URL: /submissions/validated/by/project/:projectId

where projectId (string): The ID of the project for which you want to retrieve submissions. For detailed information about this endpoint and its usage, refer to the API documentation for getting submissions.

Get All Submissions of Schema ID​

On the other hand you can fetch all submissions associated with a specific schema, filtered by submission state and Timestamp.

  • URL: /submissions/by/schema/:schemaId

where schemaId (string): The ID of the contribution schema for which you want to retrieve submissions. For detailed information about this endpoint and its usage, refer to the API documentation for getting submissions by id.

Filtering by Timestamp​

In addition to filtering by submission state and project ID, you can leverage the startDate and endDate query parameters to retrieve submissions created within a specific time frame. This capability allows for precise control over the data you fetch, enabling your application to stay in sync with the most recent contributions. You can find below more details about the Filtering Query Parameters:

  • startDate (date-time): Filter submissions that were created after this date.

  • endDate (date-time): Filter submissions that were created before this date.

  • orderBy (string): Specify the field to order the results by. Possible values include:

    • createdAt
    • name
    • state

    Default is createdAt.

  • sortOrder (string): Specify the sort order. Possible values are:

    • asc (ascending)
    • desc (descending)

    Default is desc.

By utilizing this endpoint, you can automate the retrieval of user submissions efficiently, ensuring that your application remains up-to-date with the latest contributions.

Using the results​

note

Note that, during development, you can submit your own contribution and manually download it through the Studio Dashboard to work with the result as an example. The structure will be the same through the API.

The result can be downloaded either as a complete zip, or as a JSON referencing the various components. Metadata like the author, creation date and submission state are not available within the result: it holds solely the structured data of the contribution.

For a given Schema, the submission.json will always have the same structure (json schema).

  • If the JSON is downloaded independently, external assets will be available through HTTP links
  • If the JSON is extracted from the zip archive, external assets will always have the same filenames
tip

Write the piece of code needed to use the assets, wherever this might be, grabbing the content or the path to the files through a dictionary/hash referencing all the contributions, along with your original creations, if any.