Skip to main content
Version: 3.x

Pass-Through Values

Pass-through values allow publishers to send custom key-value data when launching a survey. These values are stored and then returned on the callback when a reward is issued.

This is useful for passing internal identifiers such as:

  • Session IDs
  • Placement IDs
  • Campaign IDs
  • User segmentation flags
  • Any custom reconciliation metadata

Where to Append Pass-Through Values​

The offer entry URL is returned as one of the attributes in the campaigns#index API response.

To use pass-through values:

  1. Retrieve the offer entry URL from the campaigns#index response.
  2. Append the pass_through_values parameter to that URL before redirecting the user.

Parameter Format​

Append the following parameter to the end of the offer entry URL:

pass_through_values=<base64_encoded_json>

Encoding Requirements​

  • The value must be a JSON object (key-value pairs).
  • The JSON string must be Base64 encoded using strict encoding.
  • The encoded value must be URL-safe.

Example​

Original JSON​

{
  "session_id": "abc123",
  "placement_id": "wall_top",
  "campaign": "spring_promo"
}

Base64 Encoded​

eyJzZXNzaW9uX2lkIjoiYWJjMTIzIiwicGxhY2VtZW50X2lkIjoid2FsbF90b3AiLCJjYW1wYWlnbiI6InNwcmluZ19wcm9tbyJ9

Final Offer Entry URL​

https://www.tapresearch.com/offers/identifier/pre_survey_entry?...&pass_through_values=eyJzZXNzaW9uX2lkIjoiYWJjMTIzIiwicGxhY2VtZW50X2lkIjoid2FsbF90b3AiLCJjYW1wYWlnbiI6InNwcmluZ19wcm9tbyJ9

Callback Behavior​

When a reward callback fires:

  • The stored pass-through JSON is parsed.
  • Each key/value pair is merged into the callback payload.
  • Each value is returned as a separate top-level parameter.
  • Values are not nested under pass_through_values.

Example Callback Payload​

{
  "uid": "developers",
  "cpid": "tap_37939e4ede350f3a8d5149d2fcaa025e",
  "payout_amount": 191,
  "revenue": 0.5,
  "session_id": "abc123",
  "placement_id": "wall_top",
  "campaign": "spring_promo",
  "sig": "b438afd7426c743e777c387d7e2712d4"
}

Each pass-through value appears as its own attribute in the callback.

Error Handling​

If:

  • pass_through_values is not valid Base64, or
  • The decoded value is not valid JSON

The values will be ignored and no custom attributes will be stored.

Best Practices​

  • Keep the JSON payload small.
  • Use stable, predictable keys.
  • Avoid sending sensitive information.
  • Ensure values are unique per click when needed for reconciliation.
  • Avoid using keys that conflict with existing callback parameters.