You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+79-38Lines changed: 79 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,13 @@ To learn more about our pixels, visit: https://duckduckgo.com/duckduckgo-help-pa
9
9
10
10
Note: The effort to define our pixels is on-going. Not all our product repositories will contain pixel definitions.
11
11
12
+
## Quick Links
13
+
-[Setup](#setup)
14
+
-[Documenting a pixel](#documenting-a-pixel)
15
+
-[Experiment pixels](#experiment-pixels)
16
+
-[All other pixels](#all-other-pixels)
17
+
-[Validation](#validation)
18
+
12
19
## Setup
13
20
A repository that supports pixel definitions will have a folder setup with roughly the following structure:
14
21
```
@@ -20,56 +27,52 @@ RepoSpecificPixelFolder
20
27
--> ...
21
28
--> other_pixels.json [file for any pixels that do not belong to a feature folder]
22
29
--> ...
23
-
--> common_params.json [file that defines commonly used parameters]
24
-
--> common_suffixes.json [file that defines commonly used suffixes]
30
+
--> params_dictionary.json [file that defines commonly used parameters]
31
+
--> suffixes_dictionary.json [file that defines commonly used suffixes]
32
+
--> native_experiments.json [file that defines pixels sent by the native experiments framework]
25
33
```
26
34
27
35
You can organize the files and sub-directories within `pixels` however you like, the example above is just one option.
28
36
29
-
## Validation
30
-
**Background**:
31
-
* Validation ensures that pixel definitions conform to the [schema](./schemas/pixel_schema.json5) and follow a consistent format.
32
-
* Validation will run as part of CI, but you can also run it manually - details below.
33
-
* A repository that supports pixel definitions will have a folder setup with `package.json` pointing to this module, referred to as `PackageFolder` below.
34
-
* Note: usually `PackageFolder` is the same as the `RepoSpecificPixelFolder` referenced in the previous section.
35
-
36
-
**Pre-requisites**:
37
-
* Install Node.js: see instructions in https://nodejs.org/en/download
38
-
* Install dependencies:
39
-
```
40
-
$ cd ${PackageFolder}
41
-
$ npm i
42
-
```
43
-
44
-
**Running validation**:
45
-
```
46
-
$ cd ${PackageFolder}
47
-
$ npm run validate-defs
48
-
```
49
-
Note:
50
-
* If formatting errors are found, you can fix them with `npm run lint.fix`
51
-
* For schema validation failures, check the output and apply fixes manually
52
-
* You can also (re)validate a single file:
53
-
* Schema validation: `npx validate-ddg-pixel-defs . -f ${path to file relative to PackageFolder/pixels/ directory}`
54
-
* Formatting: `npx prettier ${path to file relative to PackageFolder/ directory} --check`
55
-
56
37
## Documenting a pixel
57
-
Each JSON file can contain multiple pixels, keyed by the static portion of the pixel name.
58
-
Add your pixel where it makes the most sense.
59
-
60
-
You can use either JSON or JSON5 (JSON with comments, trailing commas) to document your pixels.
61
-
All pixel definitions must adhere to the [pixel schemas](./schemas/pixel_schema.json5).
38
+
### Experiment pixels
39
+
Pixels sent by the [native experiments framework](https://app.asana.com/1/137249556945/project/1208889145294658/task/1209331148407154?focus=true)
40
+
must be documented separately in `native_experiments.json` and adhere to the [native experiments schema](./schemas/native_experiments.schema.json5).
41
+
42
+
**Fields**:
43
+
*`defaultSuffixes`: defines what suffixes are appended to each pixel after the cohort
44
+
* Example: Android appends `.android.[phone|tablet]` to its pixels
45
+
* See [Pixels with dynamic names](#pixels-with-dynamic-names) for more info on how to define these
46
+
*`activeExperiments`: defines each experiment with the key being the name of the experiment. Each experiment must also define:
47
+
*`cohorts`: an array of Strings defining each cohort in the experiment
48
+
*`metrics`: a collection of objects where each object is keyed by the metric name as it would appear in the pixel. Each metric must also provide:
49
+
*`description` of the metric
50
+
*`enum` of possible values
51
+
52
+
**Note**: The following are pre-defined and are automatically taken into account by the pixel schema
53
+
(you do not need to worry about defining them):
54
+
*`enrollmentDate` and `conversionWindowDays` parameters
* All other pixels must be defined in any file within the `pixels` directory and its children
61
+
* Each JSON file can contain multiple pixels, keyed by the static portion of the pixel name
62
+
* Add your pixel where it makes the most sense
63
+
* You can use either JSON or JSON5 (JSON with comments, trailing commas) to document your pixels
64
+
* Pixel definitions must adhere to the [pixel schema](./schemas/pixel_schema.json5)
62
65
63
66
Below, you'll find a walkthrough of the schema requirements and options.
64
67
As you read through, you can refer to the [pixel_guide.json](./tests/test_data/valid/pixels/pixel_guide.json5) for examples.
65
68
66
-
### Minimum requirements
69
+
####Minimum requirements
67
70
Each pixel **must** contain the following properties:
68
71
*`description` - when the pixel fires and its purpose
69
72
*`owners` - DDG usernames of who to contact about the pixel
70
73
*`triggers` - one or more of the [possible triggers](./schemas/pixel_schema.json5#27) that apply to the pixel
71
74
72
-
### Pixels with dynamic names
75
+
####Pixels with dynamic names
73
76
If the pixel name is parameterized, you can utilize the `suffixes` property.
74
77
75
78
Required properties for each suffix:
@@ -79,7 +82,13 @@ Optional properties for each suffix:
79
82
*`key` - static portion of the suffix
80
83
* JSON schema types - used to indicate constrained values for the suffix. Can be anything from https://json-schema.org/understanding-json-schema/reference/type
81
84
82
-
### Pixels with parameters
85
+
Note:
86
+
* You can utilize a 'shortcut' to point to a common suffix that's predefined in `suffixes_dictionary.json`
87
+
* See `device_type` in [pixel_guide.json](./tests/test_data/valid/pixels/pixel_guide.json5)
88
+
and [suffixes_dictionary.json](./tests/test_data/valid/suffixes_dictionary.json)
89
+
* Ordering of suffixes matters
90
+
91
+
#### Pixels with parameters
83
92
If the pixel contains parameters, you can utilize the `parameters` property.
84
93
85
94
Required properties for each parameter:
@@ -91,9 +100,41 @@ Required properties for each parameter:
91
100
Optional properties for each parameter:
92
101
* JSON schema types - used to indicate constrained parameter values. Can be anything from https://json-schema.org/understanding-json-schema/reference/type
93
102
94
-
### Temporary pixels
103
+
* You can utilize a 'shortcut' to point to a common parameter that's predefined in `params_dictionary.json`
104
+
* See `appVersion` in [pixel_guide.json](./tests/test_data/valid/pixels/pixel_guide.json5)
105
+
and [params_dictionary.json](./tests/test_data/valid/params_dictionary.json)
106
+
* Ordering of suffixes matters
107
+
108
+
#### Temporary pixels
95
109
If the pixel is temporary, set an expiration date in the `expires` property.
96
110
111
+
## Validation
112
+
**Background**:
113
+
* Validation ensures that pixel definitions conform to the [schema](./schemas/pixel_schema.json5) and follow a consistent format.
114
+
* Validation will run as part of CI, but you can also run it manually - details below.
115
+
* A repository that supports pixel definitions will have a folder setup with `package.json` pointing to this module, referred to as `PackageFolder` below.
116
+
* Note: usually `PackageFolder` is the same as the `RepoSpecificPixelFolder` referenced in the previous section.
117
+
118
+
**Pre-requisites**:
119
+
* Install Node.js: see instructions in https://nodejs.org/en/download
120
+
* Install dependencies:
121
+
```
122
+
$ cd ${PackageFolder}
123
+
$ npm i
124
+
```
125
+
126
+
**Running validation**:
127
+
```
128
+
$ cd ${PackageFolder}
129
+
$ npm run validate-defs
130
+
```
131
+
Note:
132
+
* If formatting errors are found, you can fix them with `npm run lint.fix`
133
+
* For schema validation failures, check the output and apply fixes manually
134
+
* You can also (re)validate a single file:
135
+
* Schema validation: `npx validate-ddg-pixel-defs . -f ${path to file relative to PackageFolder/pixels/ directory}`
136
+
* Formatting: `npx prettier ${path to file relative to PackageFolder/ directory} --check`
137
+
97
138
## License
98
139
DuckDuckGo Pixels Schema is distributed under the [Apache 2.0 License](LICENSE).
0 commit comments