Changes

Page history
update civicrm/donate perks documentation authored by Jérôme Charaoui's avatar Jérôme Charaoui 
fix tpo/web/donate-neo#181

the documentation was imported from the Google Doc at
https://docs.google.com/document/d/1Z33h_zzN9HQFLKJf0QlRqwSQ-N1ucIYk7Lt9403tAFM/edit?tab=t.0
Show whitespace changes
Inline Side-by-side
service/donate.md
View page @ 71636e93
......@@ -254,86 +254,29 @@ 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
## Updating 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:
The perk data is stored in the `perks.json` file at the root of the project.
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.
Updating the contents of this file should not be done manually as it required strict synchronization between the tordonate app and CiviCRM.
a. For example, `(5) [{"foo": "bar"}]` must become `{"perks": [{"foo": "bar"}]}`
Instead, the data should be [updated first in CiviCRM](service/crm#updating-premiums), then exported using the [dedicated JSON export page](https://crm.torproject.org/civicrm/tpa-perks-json).
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.
This generated data can directly replace the existing `perks.json` file.
a. For example, `"id": 1` must become `"id": "1"`.
To do this in the GitLab web interface, follow these instructions:
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.
- Go to: https://gitlab.torproject.org/tpo/web/donate-neo/-/blob/main/perks.jsonhttps://crm.torproject.org/civicrm/tpa-perks-json
- Click "Edit (single file)"
- Delete the text (click in the text box, select all, delete)
- Paste the text copied from CiviCRM
- Click "Commit changes"
- Commit message: Adapt the commit message to be a bit more descriptive (ex: "2025 YEC perks")
- Branch: commit to a new branch, call it something like "yec2025"
- Check "create a merge request for this change"
- Then click "commit changes" and continue with the merge-request.
a. For example, `"product_id.options": null` must become
`"product_id.options": ["STI-CKR-00=Sticker"]` (or something similar).
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.
Once the changes are merged, they will be deployed to staging automatically. To deploy the changes to production, after testing, trigger the manual "deploy-prod" CI job.
## Pager playbook
......
......