Supabase Analytics Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/SupabaseLogger.js
• src/index.js
• README.md
• TERMS_OF_USE.md
• src/HoloPrint.js
• src/index.html

Introduction

The Supabase Analytics Integration in HoloPrint is a privacy-focused telemetry system designed to track application usage without collecting personal user data. Its primary purpose is to record the frequency of resource pack creations and the unique structure files processed by the application. This information is used to generate public statistics regarding total packs created and unique structure file counts.

The system operates by hashing .mcstructure files using SHA-256 and sending truncated versions of these hashes to a Supabase backend. This ensures that the original file content cannot be reconstructed from the stored analytics data, maintaining user privacy while providing valuable usage metrics for the project maintainers.

Sources: README.md:95-96, TERMS_OF_USE.md:12-14, src/SupabaseLogger.js:23-26

Architecture and Components

Core Analytics Logger

The integration is centered around the SupabaseLogger class, which extends an AsyncFactory. It manages the connection to the Supabase client and provides methods for hashing and recording file usage.

The logger is initialized with a project URL and a public API key. It uses the @supabase/supabase-js library to interact with the backend via Remote Procedure Calls (RPC).

Sources: src/SupabaseLogger.js:3-16, src/index.js:15-16

Data Flow and Processing

When a user generates a resource pack, the application triggers a logging sequence. The system processes individual structure files and a combined collection of files to create unique identifiers.

The hashing process converts file contents into SHA-256 hexadecimal strings. For individual files, only the first 8 characters of the hash are sent to the server. A combined hash is also generated from all structure files in the current session to identify unique pack configurations.

Sources: src/SupabaseLogger.js:23-32, src/index.js:688-693

Technical Implementation Details

Configuration and Constants

The integration utilizes hardcoded credentials for the Supabase project, which are used to instantiate the logger within the main application loop.

Parameter	Value	Description
supabaseProjectUrl	https://gnzyfffwvulwxbczqpgl.supabase.co	The endpoint for the Supabase project.
supabaseApiKey	eyJhbGciOiJI...StDuVw	The anonymous public key for database access.
RPC Method	record_structure_usage_v2	The database function called to log usage.

Sources: src/index.js:15-16, src/SupabaseLogger.js:34

Hashing Logic

The recordPackCreation method performs the following technical steps:

1. Individual Hashing: Maps every File object to a hexadecimal string via sha256() and toHexadecimalString().
2. Truncation: Slices the resulting 64-character hash to 8 characters (shortFileHashes).
3. Combined Hashing: Concatenates all files and generates a single 8-character hash representing the entire set.
4. RPC Invocation: Passes file_hashes (array) and combined_file_hash (string) to the Supabase function.

Sources: src/SupabaseLogger.js:24-37

Implementation Example

The logger is instantiated and called within src/index.js only when the application is in production mode.

// src/index.js:688-697
if(!hasLoggedPackCreation && IN_PRODUCTION) {
    hasLoggedPackCreation = true;
    void async function() {
        supabaseLogger ??= await SupabaseLogger.new(supabaseProjectUrl, supabaseApiKey);
        try {
            await supabaseLogger.recordPackCreation(structureFiles);
        } catch(e) {
            console.error(e);
        }
    }();
}

Sources: src/index.js:688-697

Privacy and Data Security

HoloPrint adheres to a strict no-cookie policy. The analytics system is designed to be one-way and anonymous:

• No User Identifiers: No IP addresses, usernames, or browser fingerprints are recorded.
• Cryptographic Truncation: By only storing the first 4 bytes (8 hex characters) of a SHA-256 hash, it is mathematically impossible to retrieve the original .mcstructure file data from the database.
• Transparency: Daily logs and usage graphs derived from this data are made public in the holoprint-stats repository.

Sources: TERMS_OF_USE.md:12-16, README.md:95-97

Summary

The Supabase Analytics Integration provides a lightweight, anonymous method for tracking HoloPrint's growth. By leveraging Supabase's Remote Procedure Calls and client-side cryptographic hashing, the project maintainers can monitor usage trends while ensuring complete data privacy for Minecraft Bedrock creators.