Skip to content

Tracker CSV Import

Tracker CSV Import

The admin panel provides functionality to import trackers in bulk using CSV files. This guide explains how to use this feature.

Accessing the Import Feature

  1. From Campaign Management (/clients), open the campaign or child run you want to import trackers into (the "trackers" link on its card takes you to /trackers/{id})
  2. Click the "Import CSV" button on that run's tracker page
  3. A modal dialog (TrackerImportModal) will appear with instructions and options

Because the import always happens on a specific run's page, there's no separate production-run picker in the dialog — the trackers you import go into whichever run you opened.

CSV File Format

The CSV file should include the following columns:

  • ID / Name - The tracker name/identifier (required; the header can be ID, Id, Name, or Tracker ID)
  • Advertisement key - The tracker's advertisement key (required)
  • Private key - The tracker's private key (required)
  • Hashed adv key - The hashed advertisement key (required)
  • MAC Address - The tracker's MAC address (optional)

Column names are case-insensitive and can include spaces or underscores. For example, "MAC Address", "mac_address", or "MacAddress" are all valid.

Example CSV Content

Name,Advertisement key,Private key,Hashed adv key,MAC Address
c50Rvpu,5PlhQdK0WF3humRVEEmMOXGI+eqMxTc2NhWrJQ==,G1IQn4WJUS3nrnmzHtHxFcT2oSdOtbdPCk4I8g==,c50RvpugKZ3UM5AcYasM8XijrdrcMzZFt4S13LsGs4Y=,00:1A:2B:3C:4D:5E
NZ3gb4m,GHifc87f2FPmuk/IL6fDkfWtnI5zs+KtFFdXhA==,UUwgh+xbaOuXCxd2Pht7GpnPUSoIMH3M83DXFA==,NZ3gb4mv2lhAn0mIV6X1nnLPOO0cF4XTvNB2aACjVX8=,00:1A:2B:3C:4D:5F

Import Process

  1. Upload your CSV file by clicking the drop zone or by dragging and dropping the file onto it
  2. Click the "Import CSV" button to start the import process
  3. The system will validate the CSV file and import the trackers into the current run
  4. You'll receive a notification with the results of the import

Validation Rules

The import process includes several validation checks:

  • All required fields (ID, Private key, Advertisement key, Hashed adv key) must be present
  • Trackers with duplicate hashed advertisement keys will be skipped
  • The MAC Address field is optional and can be left blank

Downloading a Template

You can download a blank CSV template by clicking "Download template CSV" in the import dialog. This template includes the correct column headers (Name, Advertisement key, Private key, Hashed adv key, MAC Address) so you can fill in your own rows in the right order.

Troubleshooting

If you encounter issues during the import process:

  • Ensure your CSV file has the correct column headers
  • Check that all required fields have values
  • Verify that the CSV file is properly formatted (UTF-8 encoding is recommended)
  • Look for any error messages displayed in the import dialog

Command Line Import

The command line import script is a development-only tool. It is useful when you have the local Docker stack running and want a fast repeatable import path without using the admin panel.

python scripts/import_trackers.py <production_run_id> --csv-path path/to/your/file.csv

This script is located in the scripts directory and requires a production run ID and the path to your CSV file.

It is not a practical workflow for AWS deployments. In staging or production, use the admin panel or the API-backed import flow instead.

Cache Invalidation

When trackers are imported, the system automatically invalidates the Redis cache for:

  • The specific production run
  • All production run lists
  • All tracker lists related to the production run

This ensures that newly imported trackers appear immediately in the admin panel and frontend without requiring a manual cache flush. The cache invalidation is handled automatically by both the web interface and the local development import script.

If you're experiencing issues where newly imported trackers don't appear, please refer to the Caching System documentation for troubleshooting steps.