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.
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.
| Field | Required or optional | Example value | Description |
|---|---|---|---|
idfa | Optional if a usable idfv is present. | 11111111-2222-4333-8444-555555555555 | iOS Identifier for Advertisers. |
idfv | Optional if a usable idfa is present. | aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee | iOS Identifier for Vendor. |
install_timestamp | Optional | 1704067200 | Original install time as an integer Unix timestamp in seconds (UTC). Leave empty if unavailable. |
user_id | Optional | user_12345 | Your 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.
| Field | Required or optional | Example value | Description |
|---|---|---|---|
gaid | Optional if another usable device identifier is present. | 12345678-1234-4234-8234-123456789abc | Google Advertising ID. |
android_id | Optional if another usable device identifier is present. | a1b2c3d4e5f6789 | Android ID. Preserve leading zeros. |
appset_id | Optional if another usable device identifier is present. | 87654321-4321-4321-8321-cba987654321 | Android AppSet ID. |
install_timestamp | Optional | 1704067200 | Original install time as an integer Unix timestamp in seconds (UTC). Leave empty if unavailable. |
user_id | Optional | user_12345 | Your 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 case | Expected outcome |
|---|---|
| Imported returning user | The 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 install | A device outside the import follows normal acquisition attribution. |
| S2S event before SDK adoption | An 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 identifiers | Identify 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.
Step 6: Switch campaign links and partner configurations
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.