Skip to main content

Smart Script User Guide

What is Smart Script?​

Smart Script is a tool that converts incoming URL parameters (like utm_source=facebook) into the exact format your tracking system needs (like pid=fb). It automatically translates parameters from different sources (Facebook, Google Ads, email campaigns) into your tracking system's expected format.

Key Features​

  • Parameter Mapping: Map any incoming URL parameter to any outgoing parameter
  • Default Values: Set fallback values if a parameter is missing
  • Overrides: Remap specific incoming values to custom outgoing values
  • Web Referrer Mapping: Capture the previous page's URL as a parameter
  • Script Generation: Generate ready-to-use scripts for your website or GTM
  • Testing Tools: Built-in test page to validate your setup

Quick Start Guide​

Step 1: Create Your Smart Script​

  1. Log into your dashboard
  2. Go to: Engagement → Web-to-App → Smart Scripts
  3. Click "Add Script"

Smart Script Interface

The Smart Script interface where you configure your parameter mappings

Step 2: Basic Setup​

  1. Name your script (e.g., "Facebook Campaign Tracking")
  2. Choose your template
  3. Select your destination link

Step 3: Map Your Parameters​

  1. Click "Add Parameter"
  2. Choose what to map: Media Source, Campaign, Ad, or Custom
  3. Set outgoing parameter name (e.g., pid, camp, ad)
  4. List incoming parameters (e.g., utm_source, utm_campaign)
  5. Add default value (optional)
  6. Add overrides (optional)

Step 4: Generate and Test​

  1. Save your script
  2. Click "Generate Script" and download the file
  3. Use the test page to verify everything works

Generated Code Example​

When you save and generate your Smart Script, you'll receive a code file that looks like this:

// Initializing Smart Script arguments
var uniLinkURL = "https://trackier58.u9ilnk.me/d/6aVuVFSHbO"; // Add your Unilink here
var webReferrer = "channel";
var mediaSource = {
  "keys": [
    "utm_source"
  ],
  "defaultValue": "organic",
  "overrideValues": {}
};

// Following function can be called after apptrove smart script is embedded in the page (window.AT_SMART_SCRIPT)
window.AT_SMART_SCRIPT.generateUniLinkURL({
  uniLinkURL,
  trackingParams: {
    mediaSource: mediaSource,
    
    
  },
    webReferrer:webReferrer,
    

}).then((result) => {
  if (result) {
    console.log("Generated URL:", result.clickURL);
    // Use the URL as needed
  }
});


// You can download the minified script from:
// https://smartscript.apptrove.com/smart-script/at-smart-script-min-latest.js

// generated content end ---

How to Use the Generated Code​

  1. Download the Smart Script SDK from the URL provided in the generated code
  2. Add the SDK to your website in the <head> section: 
    <script src="https://smartscript.apptrove.com/smart-script/at-smart-script-min-latest.js"></script>
  3. Add your generated code to your website or Google Tag Manager
  4. Test the implementation using the test page

Code Explanation​

  • uniLinkURL: Your tracking link destination
  • webReferrer: Parameter name for capturing the referrer URL
  • mediaSource: Configuration for mapping incoming parameters
  • keys: Array of incoming parameters to check
  • defaultValue: Fallback value if no incoming parameter is found
  • overrideValues: Object for transforming specific values

Parameter Mapping​

Basic Example​

Incoming URL:

https://yoursite.com?utm_source=facebook&utm_campaign=summer_sale

Your Settings:

  • utm_source → pid
  • utm_campaign → camp

Resulting URL:

https://your-tracking-link.com?pid=facebook&camp=summer_sale

Advanced Features​

Multiple Incoming Parameters​

Check multiple parameters for the same outgoing parameter:

  • Incoming: utm_source, source, ref
  • Outgoing: pid
  • Uses the first parameter found

Default Values​

Set a fallback value if no parameter is found:

  • Incoming: utm_source, source
  • Default: organic
  • If neither is present, uses organic

Override Values​

Transform specific values:

  • Incoming: utm_source=facebook
  • Override: facebook → fb
  • Result: pid=fb

Web Referrer Mapping​

Setup​

  1. Scroll to "Web referrer mapping"
  2. Choose your parameter name (e.g., ref, source)
  3. The script automatically captures the referrer

Example​

Visitor comes from: https://facebook.com/your-page Your parameter: ref Result: ref=https://facebook.com/your-page

Testing Your Smart Script​

Using the Test Page​

  1. Go to: Test Script → Smart Script Test Page
  2. Enter a test URL: https://yoursite.com?utm_source=facebook&utm_campaign=summer_sale
  3. Paste your generated script
  4. Click "Run" to see the output URL

Smart Script Test Page

The Smart Script test page where you can validate your configuration

Understanding Results​

Input: https://yoursite.com?utm_source=facebook&utm_ad=ad123

Your Mappings:

  • utm_source → pid (default: organic)
  • utm_campaign → camp (default: general)
  • utm_ad → ad (default: none)

Output: https://your-tracking-link.com?pid=facebook&camp=general&ad=ad123

Common Use Cases​

Facebook Ads Campaign​

Goal: Track which Facebook ad brought the visitor Setup:

  • utm_source → pid (override: facebook → fb)
  • utm_campaign → camp
  • utm_ad → ad

Email Marketing​

Goal: Track email campaign performance Setup:

  • utm_source → pid (default: email)
  • utm_campaign → camp
  • utm_content → content

Troubleshooting​

Common Issues​

Parameter not appearing in output URL?

  • Make sure you have a mapping for that parameter

Default value not being used?

  • Check that none of your incoming parameters are present

Override not working?

  • Check for typos in your override values
  • Ensure the incoming value exactly matches your override

Script not working on your website?

  • Ensure the Smart Script SDK is loaded before your script
  • Check browser console for errors
  • Use the test page to verify your script works

Best Practices​

  1. Test Everything: Always test with the test page before going live
  2. Use Descriptive Names: Name your scripts clearly
  3. Keep It Simple: Start with basic mappings, add complexity later
  4. Monitor Performance: Check your analytics to ensure tracking works

Frequently Asked Questions​

Q: Can I use multiple parameter mappings? A: Yes! Add as many as you need for your campaign.

Q: What if I need custom parameters? A: Use the "Custom" mapping type and specify your own parameter names.

Q: Can I use this with Google Tag Manager? A: Yes! Use the "GTM" deployment mode and paste the code in a Custom HTML Tag.

Glossary​

  • Parameter: A piece of information in a URL (like utm_source=facebook)
  • Mapping: The process of converting one parameter to another
  • Incoming Parameter: The parameter that arrives with the visitor
  • Outgoing Parameter: The parameter that goes to your tracking system
  • Default Value: A fallback value used when the incoming parameter is missing
  • Override: A rule that changes a specific value (e.g., facebook → fb)
  • Referrer: The URL of the page that sent the visitor to your site
  • Smart Script: The JavaScript code that handles all the parameter translation
  • GTM: Google Tag Manager, a tool for managing website scripts

Need Help?​

If you run into any issues:

  1. Check the test page - It's the best way to debug your setup
  2. Review your mappings - Make sure all parameters are correctly configured
  3. Check browser console - Look for any JavaScript errors