@@ -254,6 +254,87 @@ using for the live site - it should have a listing for the client ID
and app secret (as well as a separate section somewhere for the
sandbox client id and app secret)."
## Treating exported perk data
As of 1/16/25, perk data exported from CiviCRM needs to be massaged into valid
JSON data before it can be used to update the `perks.json` datafile which `donate-neo`
pulls from. For reference, here are the changes which must be made to the export file
before it can be used to update the `donate-neo` repo:
1. The data object exported from CiviCRM is a square-braces array, and is not named;
to conform to JSON standards it must be wrapped in an object's curly braces and
must be named "perks". Other extraneous text prepending the array must be removed.
a. For example, `(5) [{"foo": "bar"}]` must become `{"perks": [{"foo": "bar"}]}`
2. Product `id` fields must be expressed as strings, but are exported from CiviCRM as
integers. (See [tpo/web/donate-neo/commit/b23e7fdd](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/b23e7fdd59a66658f50ede630ed924b0006a6439).) Wrap all such IDs in quotes.
a. For example, `"id": 1` must become `"id": "1"`.
3. Each "perks" array item contains a child item
`product_id.options`. If the perk does not have options (such as
the sticker pack), CiviCRM will export this field as
`null`. However, CiviCRM expects `donate-neo` to pass an option SKU
along with a perk's ID when selected - keeping this field `null`
will keep selected perks from being recorded in the CRM. (See
[tpo/web/donate-neo/commit/65144a42](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/65144a429e4f132ad64f1479eb8c8c94935897bd).) Therefore, we add a mock
option SKU in place of `null` in such cases.
a. For example, `"product_id.options": null` must become
4. Ensure all prices are expressed in number of cents (`2500`) rather than number of dollars (`25`).
5. CiviCRM is able to store and serve image files related to perks,
but we should serve these images from `donate-neo` along with the
rest of the site assets. As well, CiviCRM does not properly store
.pngs with transparency layers, rendering them instead as matte
black. In order to render and serve these images as intended, we
store them as base64-encoded strings in the JSON itself, under the
key `"product_id.imageForDonateNeo"`.
a. Ensure your string is encoded as a data URI, e.g. beginning with `data:image/png;base64,`.
6.`product_id.optionsForDonateNeo` is used by `donate-neo` to build
out the form UI used by the donor to select perk options. It was
designed to serve an option-selection UI similar to
`donate-paleo`'s, in which a given perk might have two options, the
second dependent on the first. For example, a T-shirt perk might
come in different cuts, like "Classic" and "Slim Fit", but each cut
would have separate sizes to pick from. Please ensure that
`product_id.optionsForDonateNeo` contains data formatted like so:
```
"product_id.optionsForDonateNeo": {
"Classic": {
"TSHIRT-PACK-C01": "Small",
"TSHIRT-PACK-C02": "Medium",
[...]
"TSHIRT-PACK-C07": "4XL"
}
}
```
Above, `Classic` is the parent option category, `Small` is the child option category,
and `TSHIRT-PACK-C01` is the SKU of the perk represented by these options (e.g.,
the "Classic-fit small-sized shirt".)
In the event that the given perk has no options, such as the sticker pack, you must
still express the mock option SKU from #3 in this manner, like so:
```
"product_id.optionsForDonateNeo": {
"Classic": {
"STI-CKR-00": "Sticker"
}
},
```
`donate-neo` will refrain from visually rendering single-selection option groups, but these must be
included so they can be embedded as (hidden) form elements, which are then passed along to
CiviCRM.
## Pager playbook
### High latency
...
...
@@ -569,87 +650,6 @@ sequenceDiagram
donate->>civi: Submits donation and perk info
```
### Treating exported perk data
As of 1/16/25, perk data exported from CiviCRM needs to be massaged into valid
JSON data before it can be used to update the `perks.json` datafile which `donate-neo`
pulls from. For reference, here are the changes which must be made to the export file
before it can be used to update the `donate-neo` repo:
1. The data object exported from CiviCRM is a square-braces array, and is not named;
to conform to JSON standards it must be wrapped in an object's curly braces and
must be named "perks". Other extraneous text prepending the array must be removed.
a. For example, `(5) [{"foo": "bar"}]` must become `{"perks": [{"foo": "bar"}]}`
2. Product `id` fields must be expressed as strings, but are exported from CiviCRM as
integers. (See [tpo/web/donate-neo/commit/b23e7fdd](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/b23e7fdd59a66658f50ede630ed924b0006a6439).) Wrap all such IDs in quotes.
a. For example, `"id": 1` must become `"id": "1"`.
3. Each "perks" array item contains a child item
`product_id.options`. If the perk does not have options (such as
the sticker pack), CiviCRM will export this field as
`null`. However, CiviCRM expects `donate-neo` to pass an option SKU
along with a perk's ID when selected - keeping this field `null`
will keep selected perks from being recorded in the CRM. (See
[tpo/web/donate-neo/commit/65144a42](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/65144a429e4f132ad64f1479eb8c8c94935897bd).) Therefore, we add a mock
option SKU in place of `null` in such cases.
a. For example, `"product_id.options": null` must become
