Subscription plays S3 bucket logger

The plays logger is a mechanism that allows clients to send play logs via a PARQUET file format and deliver them using a MassiveMusic S3 bucket.

By adhering to these specifications, you'll ensure that your data integrates seamlessly with our system.

If you have any questions or need further assistance, please reach out to the Client Success team.

Prerequisites

Before getting started with the Logger, please ensure that you have the following:

• Access credentials provided by us (Access Key and Secret Key) to access our S3 bucket.
• Familiarity with the PARQUET file format.
• MassiveMusic Partner ID (to be provided by MassiveMusic)

Log file

To ensure seamless integration, pay attention to three critical aspects of your data:

• Fields (Columns): The naming, case, spelling, and ordering of the columns in your file must match the exact specifications provided below.
• Data Types (Rows): Ensure that the data types in each cell match the specified types listed below.
• Values (Rows): The values in your data must adhere to the acceptable and valid formats detailed in this documentation.

Schema and Column Specifications

Your Parquet file should follow this schema with precise column names and data types:

|-- id: BYTE_ARRAY uuid (required)

• A globally unique identifier string, produced programmatically by a FUNCTION.

|-- trackid: INT32 (required)

• Not empty.
• Greater than 0.

|-- releaseid: INT32 (required)

• Not empty.
• Greater than 0.

|-- formatid: BYTE_ARRAY (required)

• Not empty.
• Greater than 0.

|-- datetimeplayed: BYTE_ARRAY (required)

• Not empty.
• Date permitted period = time now - 61 days.

|-- totaltimeplayed: INT32 (required)

• Not empty.
• Greater than or equal to 0.

|-- playmode: BYTE_ARRAY (required)

• Not empty.
• Permitted strings: "online", "offline", or "online-cached".

|-- useragent: BYTE_ARRAY (required)

• Not empty.
• Maximum 255 characters.

|-- userid: BYTE_ARRAY (required)

• Not empty.

|-- partnerid: BYTE_ARRAY (required)

• Not empty, your partnerid.

|-- shopid: INT32 (required)

• Null.

|-- country: BYTE_ARRAY (required)

• Not empty.
• Length = 2.
• Permitted countries: See here

Example Row Representation

Here's an example of a row in your log file, adhering to the specified schema and requirements

{
  "id": "482a552b-2926-4e2f-9dc1-45cb8798accf",
  "trackid": 135383009,
  "releaseid": 17967137,
  "formatid": "56",
  "datetimeplayed": "2024-03-27T10:49:21Z",
  "totaltimeplayed": 264,
  "playmode": "online",
  "useragent": "some-user-agent",
  "userid": "143229601",
  "partnerid": "12345",
  "shopid": null,
  "country": "CH"
}

Delivery to Our S3 Bucket

To deliver the logs to our S3 bucket, please follow these steps:

1. Access Credentials: Use the provided Access Key and Secret Key to authenticate your requests to our S3 bucket.
2. Delivery Path: Specify the designated delivery path within our S3 bucket where the logs should be uploaded.
3. PARQUET files containing logs of type ‘subscription_stream,’ should be written here:
   s3://7digital-glue-data-prod/receipts/subscription_stream/(partnerID)/
4. File Naming Convention:
   YYYY-MM-DD-LOGTYPE-NUMBERINSERIES.parquet
   Example: 2023-06-12-subscription_stream_000000000001.parquet
5. Frequency: Daily usage

Troubleshooting

If there's an error in one of the files you submit we will notify you.

We will notify you should you be required to resubmit logs, please use the designated delivery paths to submit the revised logs once the error has been fixed.

• PARQUET files containing logs of type ‘subscription_stream’ should be written here:
  s3://7digital-glue-data-prod/failures/subscription_stream/(partnerID)