index.rst (8944B)
1 ======================== 2 Installation Attribution 3 ======================== 4 5 *Installation Attribution* is a system that allows us to do a few things: 6 7 - Gauge the success of marketing campaigns 8 - Determine (roughly) the origin of an installer that a user ran 9 - Support the Return to AMO workflow. 10 11 We accomplish these things by adding an *attribution code* to Firefox installers which generally contains information supplied by www.mozilla.org (Bedrock and related services). This information is read by Firefox during and after installation, and sent back to Mozilla through Firefox Telemetry. 12 13 The following information is supported by this system: 14 15 * Traditional `UTM parameters <https://en.wikipedia.org/wiki/UTM_parameters>`_ (*source*, *medium*, *campaign*, and *content*) 16 * *experiment* 17 * *variation* 18 * *ua* 19 * *dltoken* 20 * *dlsource* 21 * *msstoresignedin* 22 * *msclkid* 23 24 Descriptions of each of these can be found in :ref:`the Telemetry Environment documentation <environment>`. 25 26 --------------------------------------- 27 Firefox Windows Installers & macOS DMGs 28 --------------------------------------- 29 30 Installs done through Windows stub or full NSIS installers or macOS DMGs are capable of being attributed. When these packages are created, they are given initial attribution data of *dlsource=mozillaci*. Users who download their package via www.mozilla.org will typically have this attribution data overwritten (unless they have Do-not-track (DNT) enabled), with *dlsource=mozorg*, a *dltoken*, and whatever UTM parameters Bedrock deems appropriate. 31 32 An additional complication here is that the attribution system is used (or abused, depending on your view) to support the Return to AMO workflow -- forcing the *campaign* and *content* UTM parameters to specific values. 33 34 The below diagram illustrates the flow of the cases above: 35 36 .. mermaid:: 37 38 flowchart TD 39 subgraph Legend 40 direction LR 41 start1[ ] --->|"(1) Bedrock, Do-Not-Track enabled"| stop1[ ] 42 start2[ ] --->|"(2) Bedrock, Do-Not-Track disabled"| stop2[ ] 43 start3[ ] --->|"(3) Bedrock via Search Engine"| stop3[ ] 44 start4[ ] --->|"(4) Bedrock via Return to AMO flow"| stop4[ ] 45 start5[ ] --->|"(5) Direct download from CDN Origin"| stop5[ ] 46 start6[ ] --->|"Common Paths"| stop6[ ] 47 48 %% Legend colours 49 linkStyle 0 stroke-width:2px,fill:none,stroke:blue; 50 linkStyle 1 stroke-width:2px,fill:none,stroke:green; 51 linkStyle 2 stroke-width:2px,fill:none,stroke:red; 52 linkStyle 3 stroke-width:2px,fill:none,stroke:purple; 53 linkStyle 4 stroke-width:2px,fill:none,stroke:pink; 54 end 55 56 subgraph Download Flow 57 User([User]) 58 Search[Search Engine] 59 AMO[AMO<br>addons.mozilla.org] 60 Bedrock[Bedrock<br>mozilla.org] 61 Bouncer[Bouncer<br>download.mozilla.org] 62 CDNOrigin[CDN Origin<br>archive.mozilla.org] 63 CDN[CDN<br>download-installer.cdn.mozilla.net] 64 Attr[Attribution Service<br>stubdownloader.services.mozilla.net] 65 AttrCDN[Attribution CDN<br>cdn.stubdownloader.services.mozilla.net] 66 Inst([Installer Downloaded]) 67 68 %% Case 1: Bedrock, DNT enabled 69 User ----> Bedrock 70 Bedrock ---->|"No attribution data set"| Bouncer 71 Bouncer ----> CDN 72 CDN ---->|"Contains static attribution data:<br><i>dlsource</i>: mozillaci"| Inst 73 74 linkStyle 6,7,8,9 stroke-width:2px,fill:none,stroke:blue; 75 76 %% Case 2: Bedrock, DNT disabled 77 User ---> Bedrock 78 79 linkStyle 10 stroke-width:2px,fill:none,stroke:green; 80 81 %% Case 3: Bedrock via Search Engine 82 User ----> Search 83 Search ---->|"Sets UTM parameters"| Bedrock 84 85 linkStyle 11,12 stroke-width:2px,fill:none,stroke:red; 86 87 %% Case 4: Bedrock via Return to AMO flow 88 User ---->|"Initiates Return-to-AMO request"| AMO 89 AMO ---->|"Sets <i>campaign</i> and<br><i>content</i> UTM parameters"| Bedrock 90 91 linkStyle 13,14 stroke-width:2px,fill:none,stroke:purple; 92 93 %% Case 5: Direct download from CDN 94 User --> CDNOrigin 95 CDNOrigin -->|"Contains static attribution data:<br><i>dlsource</i>: mozillaci"| Inst 96 97 linkStyle 15,16 stroke-width:2px,fill:none,stroke:pink; 98 99 %% Common links for cases 2, 3, and 4 100 Bedrock ---->|"Attribution data forwarded:<br><i>dlsource</i>: mozorg<br><i>dltoken</i>: present<br>any UTM parameters set"| Bouncer 101 Bouncer ---->|"Forwards attribution data"| Attr 102 Attr <---->|"Fetches installer"| CDN 103 Attr ---->|"Places modified installer<br>on Attribution CDN"| AttrCDN 104 AttrCDN ---->|"Contains dynamic attribution data:<br><i>dlsource</i>: mozorg<br><i>dltoken</i>: present<br>any UTM parameters set"| Inst 105 106 %% Common links for everything 107 CDN <---->|"Fetches installer"| CDNOrigin 108 end 109 110 ~~~~~~~ 111 Windows 112 ~~~~~~~ 113 114 Windows attribution is implementing by injecting data into the signature block of NSIS installers at download time. This technique is described in the "Cheating Authenticode" section of `this Microsoft blog post <https://learn.microsoft.com/en-ca/archive/blogs/ieinternals/caveats-for-authenticode-code-signing#cheating-authenticode>`_. 115 116 ~~~~~ 117 macOS 118 ~~~~~ 119 120 macOS attribution is implemented by adding a ``com.apple.application-instance`` extended attribute to the ``.app`` bundle at download time. This special extended attribute is explicitly *not* part of the digital signature of the ``.app`` bundle as per `this Apple technical note <https://developer.apple.com/library/archive/technotes/tn2206/_index.html#//apple_ref/doc/uid/DTS40007919-CH1-TNTAG401>`_. 121 122 123 --------------- 124 Microsoft Store 125 --------------- 126 127 Firefox installs done through the Microsoft Store support extracting campaign IDs that may be embedded into them. This allows us to attribute installs through different channels by providing particular links to the Microsoft Store with attribution data included. For example: 128 129 `ms-windows-store://pdp/?productid=9NZVDKPMR9RD&cid=source%3Dgoogle.com%26medium%3Dorganic%26campaign%3D(not%20set)%26content%3D(not%20set) <ms-windows-store://pdp/?productid=9NZVDKPMR9RD&cid=source%3Dgoogle.com%26medium%3Dorganic%26campaign%3D(not%20set)%26content%3D(not%20set)>`_ 130 131 132 `https://www.microsoft.com/store/apps/9NZVDKPMR9RD?cid=source%3Dgoogle.com%26medium%3Dorganic%26campaign%3D(not%20set)%26content%3D(not%20set) <https://www.microsoft.com/store/apps/9NZVDKPMR9RD?cid=source%3Dgoogle.com%26medium%3Dorganic%26campaign%3D(not%20set)%26content%3D(not%20set)>`_ 133 134 Microsoft Store Ads presents its Ads Campaign ID to installed applications as a uniquely formatted ``storeBingAd_[uuid]``, for example ``storeBingAd_45cbbf091fb541f0ae959d50ffb8c5b8``. Firefox records this as ``msclkid=[uuid]``, for example ``msclkid=45cbbf091fb541f0ae959d50ffb8c5b8`` in installation attribution. 135 136 137 For more on how custom campaign IDs work in general in the Microsoft Store environment, `see Microsoft's documentation <https://docs.microsoft.com/en-us/windows/uwp/publish/create-a-custom-app-promotion-campaign>`_. 138 139 The Microsoft Store provides a single `cid` (Campaign ID). Their documentation claims it is limited to 100 characters, although in our own testing we've been able to retrieve the first 208 characters of Campaign IDs. Firefox expects this Campaign ID to follow the same format as stub and full installer attribution codes, which have a maximum of length of 1010 characters. Since Campaign IDs are more limited than what Firefox allows, we need to be a bit more thoughtful about what we include in them vs. stub and full installer attribution. At the time of writing, we've yet to be able to test whether we can reliably pull more than the advertised 100 characters of a Campaign ID in the real world -- something that we should do before we send any crucial information past the first 100 characters. 140 141 In addition to the attribution data retrieved through the campaign ID, we also add an extra key to it to indicate whether or not the user was signed into the Microsoft Store when they installed. This `msstoresignedin` key can have a value of `true` or `false`. 142 143 There are a couple of other caveats to keep in mind: 144 145 * A campaign ID is only set the *first* time a user installs Firefox through the Store. Subsequent installs will inherit the original campaign ID (even if it was an empty string). This means that only brand new installs will be attributed -- not reinstalls. 146 * At the time of writing, it is not clear whether or not installs done without being signed into the Microsoft Store will be able to find their campaign ID. Microsoft's documentation claims they can, but our own testing has not been able to verify this.