Skip to main content

Migrate to justtrack

If you're moving from another mobile measurement partner (MMP), import your existing users before their first justtrack SDK attribution so justtrack can recognize them when they open the updated app. This guide covers user identities and original install dates. Historical attribution, events, revenue, and Return on Ad Spend (ROAS) are separate migration topics.

Complete the import before submitting your app

Don't submit your apps to an app store before justtrack completes your data import. This can cause justtrack to record existing users as new users.

Before-release checklist​

  • Test SDK integration and event tracking.
  • Agree on comma-separated values (CSV) samples, identifier matching, and optional-field handling with justtrack.
  • Confirm import completion and the four validation cases, and document exclusions.
  • Include users acquired between the export cutoff and rollout.
  • Agree on a cutover for the SDK rollout, campaign links, and partner settings.

Step 1: Prepare your app and test the SDK​

Connect your app with justtrack and verify its iOS bundle ID or Android package name. Follow Set up the SDK and test attribution, events, and any revenue tracking you use.

Agree on the rollout date and campaign cutover with justtrack at support@justtrack.io. If you use your own user IDs, configure Set a user ID and use the same values in your backend integration. Test with a controlled population before exposing existing production users to the SDK.

Step 2: Export existing-user data​

Export device identifiers and, where available, the original install timestamp and your own user ID. You can obtain this data from your previous MMP, your backend, stored install callbacks, or a data warehouse.

Send a small representative sample to support@justtrack.io before preparing the full export. Include the target app, operating system, planned rollout date, and available identifiers. Agree on the export cutoff and how to include users acquired between that cutoff and the rollout.

Step 3: Agree on the import data and CSV format​

Provide one CSV per app and operating system. Each row represents one installation and contains all available identifiers for that installation. An account with multiple installations needs one row per installation.

Name each file <bundle_id>_<os_name>.csv. Use the iOS bundle ID or Android package name for bundle_id, and ios or android for os_name.

CSV columns​

Each row requires at least one usable device identifier for its operating system. Individual device identifier fields may be empty when another usable identifier is present. install_timestamp and user_id are optional; user_id alone doesn't replace a device identifier. Timestamps use Coordinated Universal Time (UTC).

iOS​

Use ios for os_name. Provide idfa, idfv, or both for each installation.

FieldRequired or optionalExample valueDescription
idfaOptional if a usable idfv is present.11111111-2222-4333-8444-555555555555iOS Identifier for Advertisers.
idfvOptional if a usable idfa is present.aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeeeiOS Identifier for Vendor.
install_timestampOptional1704067200Original install time as an integer Unix timestamp in seconds (UTC). Leave empty if unavailable.
user_idOptionaluser_12345Your own user ID when using Set a user ID. Use the same value as in the SDK and backend.

Example: com.example.app_ios.csv

idfa,idfv,install_timestamp,user_id
11111111-2222-4333-8444-555555555555,aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee,1704067200,user_12345
,bbbbbbbb-cccc-4ddd-8eee-ffffffffffff,,user_67890

Android​

Use android for os_name. Provide the available gaid, android_id, and appset_id values together in each row. At least one must be usable for matching.

FieldRequired or optionalExample valueDescription
gaidOptional if another usable device identifier is present.12345678-1234-4234-8234-123456789abcGoogle Advertising ID.
android_idOptional if another usable device identifier is present.a1b2c3d4e5f6789Android ID. Preserve leading zeros.
appset_idOptional if another usable device identifier is present.87654321-4321-4321-8321-cba987654321Android AppSet ID.
install_timestampOptional1704067200Original install time as an integer Unix timestamp in seconds (UTC). Leave empty if unavailable.
user_idOptionaluser_12345Your own user ID when using Set a user ID. Use the same value as in the SDK and backend.

Example: com.example.app_android.csv

gaid,android_id,appset_id,install_timestamp,user_id
12345678-1234-4234-8234-123456789abc,a1b2c3d4e5f6789,87654321-4321-4321-8321-cba987654321,1704067200,user_54321
22222222-3333-4444-8555-666666666666,,,,
CSV formatting
  • Use UTF-8, commas, and the header order shown above: four fields per iOS row and five per Android row.
  • Leave unavailable values empty and preserve their commas, including trailing commas. Don't use placeholder values such as null, N/A, or zero-filled identifiers.
  • Keep identifiers as text and preserve their original formatting. Quote values containing commas, double quotes, or line breaks, and escape a double quote within a quoted value by doubling it.
  • Use original install timestamps in seconds, not milliseconds or app-update dates.

The examples contain synthetic data. If your backend identifies users by your own user ID, include it in user_id and validate the mapping during import. The SDK's user ID requirements also apply: fewer than 4096 characters, using printable ASCII (U+0020–U+007E).

Step 4: Import and validate existing users​

Request the import through support@justtrack.io. Once support has reviewed the sample, provide the full CSV files through the agreed transfer method, with their app, platform, export cutoff, and row counts.

Before rollout, ask justtrack at support@justtrack.io to confirm completion, reconcile imported and rejected records, and resolve or document exclusions. A file upload or accepted API request alone doesn't confirm successful identity matching.

Confirm the following cases, including server-to-server (S2S) events:

Test caseExpected outcome
Imported returning userThe first SDK contact matches the existing installation. The app update doesn't itself create a new acquisition. Verify the supplied install date or the agreed handling of an omitted timestamp.
Genuine new installA device outside the import follows normal acquisition attribution.
S2S event before SDK adoptionAn event from a user on an older app version resolves through the imported identity and any required custom user ID mapping, and appears in reporting.
Missing or conflicting identifiersIdentify unmatchable records for review. Confirm that empty optional fields follow the agreed handling.

Step 5: Release the app and verify reporting​

After justtrack confirms the import and the validation cases pass, release the app version with the SDK. Check returning users and genuine new installs separately, including events and revenue where configured. Use the Installs definition when interpreting acquisition counts; normal reattribution rules still apply.

Prepare partner settings in advance and activate them at the agreed cutover. Update campaign links and postbacks using the Promote documentation and Tracking URLs guide.

With the app version containing the SDK live, validate the full path from an ad interaction to an install, reporting, and the partner postback. If both MMPs run temporarily, agree which system sends each partner signal and when to retire the previous configuration.

If your SDK rollout has already started​

Contact support@justtrack.io with the rollout date, app versions, available identifiers, original install dates where available, and affected event references. Handle these cases separately:

  • Existing users not yet seen by justtrack: arrange the import before their first SDK attribution where possible.
  • Users already recorded: ask to review overlaps and possible install backdating. This doesn't retroactively change conversions already attributed.
  • Missing S2S events: first confirm identity availability for the original event times and reconcile against successfully processed events. Replay only confirmed missing events, preserving their original happenedAt. Time-limited deduplication doesn't make a replay of the entire history safe.