Fundraising/External-facing/E-mail preference center
Overview
The email preference center is a standalone wiki that uses civiproxy to talk to civicrm.
Note that the links below include checksums that will have expired by the time you read this page. To get an updated checksum for a contact, just browse to their contact summary page in your local Civi instance and look for the 'email preference center' link on the right side just under the relationships block.
Links
URL Structure
https://fundraising.frdev.wikimedia.org/index.php/Special:EmailPreferences/emailPreferences?contact_id=<id>&checksum=<checksum>
Sample links (Local instance)
Preference Center
Translated Preference Center (adding &uselang=)
Civiproxy JSON response
Phabricator Epic
Create Preference Center for donors to manage email subscription preferences - https://phabricator.wikimedia.org/T125272
Documentation of Email Preference
https://docs.google.com/document/d/1wKtGxJn06bs6OGAFV7DKUfVw2salKdU_NAUn5SMGks0
User interface Design
File paths
- HTML: src/email-pref-ctr/extensions/DonationInterface/email_forms/templates/emailPreferences.html.mustache
- CSS: src/email-pref-ctr/extensions/DonationInterface/modules/css/emailPreferences.css
- JS: src/email-pref-ctr/extensions/DonationInterface/modules/js/ext.donationInterface.emailPreferences.js
- Get Email Preference Info from civiproxy
- dev/src/civi-sites/wmff/drupal/sites/default/civicrm/extensions/wmf-civicrm/api/v3/Civiproxy/Getpreferences.php
- Update Email Preference with Queue
- /src/civi-sites/wmff/drupal/sites/default/civicrm/extensions/wmf-civicrm/CRM/Queue/PreferencesQueueConsumer.php
- /src/civi-sites/wmff/drupal/sites/default/civicrm/extensions/wmf-civicrm/api/v3/Preferencesqueue/Consume.php
- /src/civi-sites/wmff/drupal/sites/default/civicrm/extensions/wmf-civicrm/api/v3/Preferences/Create.php
Queue
drush cvapi Preferencesqueue.consume time_limit=1000 max_batch_size=1
Unit Test
./vendor/bin/phpunit --filter testEmailPreferenceCenterUpdateApi
CiviCRM
- Local civi url to see the api: http://wmff.localhost:32353/civicrm/api3#explorer: select contact -> get -> then input the contact id and the checksum there to see the donor info
- Check user from civi: https://wmff.localhost:32353/civicrm/contact/view?reset=1&cid=6
- From edit view, you will see the opt in from communication section, home email, and their prefer language, and Email preference Country.
Civiproxy
Official documentation: https://docs.civicrm.org/civiproxy/en/latest/
Our repo: https://gerrit.wikimedia.org/r/q/project:wikimedia/fundraising/crm/civiproxy
- Link to test from docker add in key and hash from a test contact (need checksum and contact_id):
- https://localhost:9005/rest.php?entity=civiproxy&action=getpreferences&key=SITE_KEY&version=3&json=1&checksum=&api_key=API_KEY&contact_id=
Deploying
The email preference center is under the project donorwiki. Deploying is the same steps as deploying Donation Interface and then running fundraising_code_update with the project donorwiki
There is a settings file in localsettings in a folder called civiproxy. This can be deployed to the civiproxy project
Local Troubleshooting
To make CiviProxy work with the local self-signed cert, we mount an edited copy of the civiproxy file proxy.php from the top-level config/civiproxy folder OVER the one found in src/civiproxy/proxy. The file is edited to turn the certificate validation off when making CURL requests. We also mount config.php into that same folder.
If for some reason you see an error one of those file mounts may have failed. This may fix it:
docker-compose restart civiproxy
Note that this file mount may fail when using git to check out a different version of the proxy.php file in the civiproxy repo.
Translations
The languages available are in DI config named DonationInterfaceEmailPreferencesLanguages
The strings themselves live in emailForms/i18n
Proposed Email Update Flows
I'm working on the phabricator ticket,T353376 about Email preference center (EPC) emails overwriting contact emails. In order to understand the requirements/proposed solution, I've gone ahead to draw up a flow of how we currently manage contact emails and the proposed solution to prevent this overwrite.
Regular recurring donations through Payments form (example Credit Card)
The contact record created from this donation is only managed on CiviCRM. The only email updates for this contact record would be from Deduper and Email Preference Center. Updating the email through EPC would cause an overwrite to the primary email. This overwrite could potentially lead to duplicate contact records.
Proposal is to have the email preference center set the new email to primary and keep the old email with the label set to "Other".
Donations through wallets like Paypal/Venmo/GPay/ApplePay
The contact record created from this donation is managed on CiviCRM, however the donor can also update their contact record on the wallet provider. Therefore email updates on the contact record would be from either Deduper, Email Preference Center, or the Wallet. Updating the email through Email preference center currently works like in Cards, however when a recurring payment from the wallet is imported, the new email from Email preference center is overwritten by the wallet email. This could be disastrous when the donor specifically wants to use a different email for donations.
Proposal for updates through the EPC is to assign the email through preference center as primary and keep the old email with label set to other. If the email from the recurring donation is neither of the two, then this new email can be set to the billing address.
Donations through Fundraiseup
The contact record created from this donation is managed on CiviCRM, however with Donor portal the donor may choose to update their contact records including email. This update currently would overwrite the set primary email on Civi when imported through a transaction. Donor Portal is not activated currently, however we need to remember to turn off email modifications from either one of Email Preference center or Fundraiseup's Donor portal to avoid any confusions about which emails to set as primary.
Proposal for updates through Fundraisup donor portal or email preference center is to assign the imported email as primary. In addition to this, Fundraiseup new rest api has an endpoint that could allow the modification of contact records on Fundraiseup. Through the API we can ensure data consistency on both Civi and Fundraiseup on contact updates.