Onboarding Deep Link Parameters: What Data to Pass

Deep links that drive app installs carry parameters through the install process via deferred deep linking. These parameters determine what the user sees during onboarding, which steps they skip, and what context personalizes their experience. Choosing the right parameters is the difference between a personalized onboarding and a generic one.

For personalization strategies, see Personalized Onboarding Flows with Deep Link Data. For invite-specific flows, see Invite Link Onboarding: From Invitation to Active User. For a broader guide to deep link parameter design, see Deep Link Parameters: A Complete Guide.

Parameter Categories

1. Attribution Parameters

These identify where the user came from:

Parameter	Example Value	Purpose
utm_source	instagram, google, newsletter	Traffic source
utm_medium	social, cpc, email	Marketing channel
utm_campaign	summer_sale_2026	Campaign name
utm_content	hero_banner_v2	Creative variant
utm_term	running+shoes	Search keyword

https://go.yourapp.com/signup?utm_source=instagram&utm_medium=social&utm_campaign=summer_sale

These parameters don't directly affect onboarding screens, but they're essential for measuring which acquisition channels produce the most engaged users.

2. Referral Parameters

These connect the new user to an existing user:

Parameter	Example Value	Purpose
ref	user_abc123	Referrer's user ID
referrer_name	Sarah	Referrer's display name
referral_code	SARAH-2026	Human-readable referral code
reward	10	Reward amount
reward_type	credit	Reward type (credit, discount, etc.)

https://go.yourapp.com/refer/SARAH-2026?ref=user_abc123&referrer_name=Sarah&reward=10

3. Content Parameters

These point to specific content the user was interested in:

Parameter	Example Value	Purpose
product_id	prod_xyz789	Specific product
category	running	Product category
content_id	article_456	Specific article or content piece
content_type	playlist	Type of content
collection_id	coll_abc	Collection or list

https://go.yourapp.com/product/prod_xyz789?category=running

4. Promotional Parameters

These carry offer and discount information:

Parameter	Example Value	Purpose
promo	SUMMER50	Promo code
discount	20	Discount percentage
offer_id	offer_123	Server-side offer reference
trial_days	14	Extended trial period
plan	premium	Pre-selected plan

https://go.yourapp.com/signup?promo=SUMMER50&discount=20&plan=premium

5. Context Parameters

These provide situational context:

Parameter	Example Value	Purpose
role	seller, buyer	User type for marketplace apps
team_id	team_abc	Team to join
event_id	evt_123	Event context
partner	shopify	Partner integration source
locale	es_MX	Preferred language
source_screen	pricing_page	Where on your website they clicked

https://go.yourapp.com/join?team_id=team_abc&role=member&partner=slack

What NOT to Put in Parameters

Never Include

Data	Why Not	Alternative
Email addresses	PII in URLs, logged everywhere	Use a session token
Passwords	Security risk	Never pass credentials in URLs
SSNs, account numbers	Regulatory violation	Use encrypted server-side lookup
Full names	PII concerns	Use first name only or referral code
Phone numbers	PII, regulatory	Use a session token
Payment info	PCI compliance violation	Never expose in URLs

Use Tokens Instead

For sensitive data, use an opaque token that maps to server-side data:

// Bad
const link = `https://go.yourapp.com/[email protected]&name=Jane+Smith`;

// Good
const sessionToken = await createPreSignupSession({
  email: '[email protected]',
  name: 'Jane Smith',
  preferences: { category: 'fitness' },
});

const link = `https://go.yourapp.com/signup?session=${sessionToken}`;

The app fetches the pre-filled data from your server using the token, keeping PII out of the URL.

Parameter Design Rules

1. Keep Parameter Names Short and Consistent

// Good: short, consistent naming
const params = {
  ref: 'user_abc',      // referrer
  src: 'instagram',      // source (alias for utm_source)
  cat: 'running',        // category
  pid: 'prod_xyz',       // product ID
  promo: 'SUMMER50',     // promo code
};

// Bad: verbose, inconsistent
const params = {
  referrer_user_id: 'user_abc',
  trafficSource: 'instagram',
  product_category: 'running',
  productId: 'prod_xyz',
  promotional_code: 'SUMMER50',
};

Short parameter names reduce URL length (important for SMS and social sharing where character limits exist).

2. Use IDs, Not Names

// Good: IDs are stable
const link = `https://go.yourapp.com/refer?ref=user_abc123`;

// Bad: names can change and have encoding issues
const link = `https://go.yourapp.com/refer?referrer_name=María%20García`;

Look up names server-side using the ID.

3. Validate All Parameters on Receipt

async function processDeepLinkParams(params) {
  const validated = {};

  // Validate referrer exists
  if (params.ref) {
    const referrer = await getUser(params.ref);
    if (referrer) {
      validated.referrer = referrer;
    }
  }

  // Validate product exists
  if (params.pid) {
    const product = await getProduct(params.pid);
    if (product && product.isActive) {
      validated.product = product;
    }
  }

  // Validate promo code
  if (params.promo) {
    const promo = await validatePromoCode(params.promo);
    if (promo && promo.isActive) {
      validated.promo = promo;
    }
  }

  // Sanitize string params
  if (params.referrer_name) {
    validated.referrerName = sanitize(params.referrer_name);
  }

  return validated;
}

4. Set Defaults for Missing Parameters

function getOnboardingConfig(params) {
  return {
    source: params.utm_source || 'organic',
    campaign: params.utm_campaign || null,
    referrer: params.ref || null,
    product: params.pid || null,
    promoCode: params.promo || null,
    role: params.role || 'buyer', // Default role
    locale: params.locale || getDeviceLocale(),
    flow: params.ref ? 'referral' : params.pid ? 'product' : 'default',
  };
}

Parameter Combinations

Common Link Templates

const linkTemplates = {
  referral: {
    path: '/refer/{code}',
    requiredParams: ['ref', 'referrer_name'],
    optionalParams: ['reward', 'reward_type'],
    example: '/refer/SARAH-2026?ref=user_abc&referrer_name=Sarah&reward=10',
  },

  productAd: {
    path: '/product/{id}',
    requiredParams: ['utm_source', 'utm_campaign'],
    optionalParams: ['promo', 'category'],
    example: '/product/prod_xyz?utm_source=facebook&utm_campaign=summer_sale&promo=SUMMER50',
  },

  teamInvite: {
    path: '/join/{team_id}',
    requiredParams: ['team_id', 'role'],
    optionalParams: ['inviter_name', 'inviter_id'],
    example: '/join/team_abc?role=member&inviter_name=Alex',
  },

  contentShare: {
    path: '/share/{type}/{id}',
    requiredParams: ['content_type', 'content_id'],
    optionalParams: ['sharer_name', 'ref'],
    example: '/share/playlist/pl_123?sharer_name=Mike&ref=user_def',
  },
};

How Parameters Map to Onboarding Steps

For a complete guide to using these parameters for contextual routing, see Contextual Deep Linking Guide.

Parameters Present	Onboarding Effect
ref + referrer_name	Show referral welcome, acknowledge referrer
pid + category	Skip category selection, show product first
promo + discount	Show promo banner, pre-apply discount
team_id + role	Skip role selection, auto-join team
utm_source=ad + utm_campaign	Show campaign-specific landing
None (organic)	Full standard onboarding

Debugging Parameters

Logging

Log parameters on receipt for debugging (but sanitize sensitive data):

function logDeepLinkParams(params) {
  const sanitized = { ...params };

  // Mask any potential PII
  if (sanitized.email) sanitized.email = '***@***.***';
  if (sanitized.session) sanitized.session = sanitized.session.slice(0, 8) + '...';

  console.log('Deep link params received:', sanitized);

  analytics.track('deep_link_params_received', {
    paramCount: Object.keys(params).length,
    hasReferral: params.ref ? true : false,
    hasProduct: params.pid ? true : false,
    hasPromo: params.promo ? true : false,
    source: params.utm_source || 'none',
  });
}

Testing Parameter Flows

Create test links with different parameter combinations and verify each onboarding path:

const testLinks = [
  { name: 'Referral', url: 'https://go.yourapp.com/refer/TEST?ref=test_user&referrer_name=Test' },
  { name: 'Product', url: 'https://go.yourapp.com/product/test_prod?category=test' },
  { name: 'Campaign', url: 'https://go.yourapp.com/signup?utm_source=test&utm_campaign=test_campaign' },
  { name: 'Team invite', url: 'https://go.yourapp.com/join/test_team?role=member' },
  { name: 'Organic', url: 'https://go.yourapp.com/' },
];

For dynamic routes, see the dynamic routes documentation. For deep linking features, see Tolinku deep linking. For onboarding use cases, see the onboarding documentation.