From a54a9d8f3556f1ba6fa2f41426fbd1abae0442c8 Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Thu, 2 Aug 2018 09:41:43 +0100 Subject: [PATCH 1/9] Add first draft of Notify integration guidance Adapted from: https://gist.github.com/quis/1136d255a5cdc47f4b72bc5bf234cf97 --- docs/documentation/using-notify.md | 48 ++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/documentation/using-notify.md diff --git a/docs/documentation/using-notify.md b/docs/documentation/using-notify.md new file mode 100644 index 0000000000..77147c2169 --- /dev/null +++ b/docs/documentation/using-notify.md @@ -0,0 +1,48 @@ +To set it locally, run this command in your Terminal, in the root +folder of your prototype: +```shell + echo NOTIFYAPIKEY=xxxxxxx >> .env +```` +(where xxxxxxx is a key you’ve created in Notify). This creates a file +named `.env` which contains your API key. + +To set it on Heroku, go to the settings page on your app, click +‘reveal config vars’ and enter NOTIFYAPIKEY and the value of the key +in the two boxes. + +Add this code to the top of routes.js: +```javascript +var NotifyClient = require('notifications-node-client').NotifyClient, + notify = new NotifyClient(process.env.NOTIFYAPIKEY); +``` + +`process.env.NOTIFYAPIKEY` is a special kind of variable that Node +pulls from the environment your prototype is running in. + +*** + +Make a page to collect the phone number or email address. This page +needs a textbox called 'email', to match req.body.email below, eg + + +You can change it to something else, eg `phoneNumber`, but you need to +change it in the code below as well. + +This code goes at the bottom of routes.js: + +```javascript +router.post('/page-with-email-or-phone-input', function (req, res) { + + notify.sendEmail( + // this long string is the template ID, get it from Notify + '24a8b897-2de9-4a9f-a2db-b6ef682f799a', + req.body.email, + {} + ); + + // This URL can wherever you want to send people to after the + // emailhas been sent + res.redirect('/confirmation-page'); + +}); +``` From 8102a2d3916db43dd03de001cd46040774736b01 Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Fri, 28 Sep 2018 10:47:31 +0100 Subject: [PATCH 2/9] Rewrite instructions to add more context The previous instructions were a very bare-bones draft which assumed a lot of context. This commit attempts to rewrite them for someone without knowledge of what Notify is, or how an API works. Hopefully this is enough so that someone who is confident using the prototype kit can integrate their prototype with Notify. --- docs/documentation/using-notify.md | 130 ++++++++++++++++++++++++----- 1 file changed, 109 insertions(+), 21 deletions(-) diff --git a/docs/documentation/using-notify.md b/docs/documentation/using-notify.md index 77147c2169..313b408dfe 100644 --- a/docs/documentation/using-notify.md +++ b/docs/documentation/using-notify.md @@ -1,16 +1,68 @@ -To set it locally, run this command in your Terminal, in the root -folder of your prototype: +# Using GOV.UK Notify to prototype emails and text messages + +You can use GOV.UK Notify to send text messages or emails when users +interact with your prototype. For example you could send users a +confirmation email sent at the end of a journey. + +## Sign up for a GOV.UK Notify account + +If you have a government email address you can sign up for an account at +https://www.gov.uk/notify + +You need an account before you can use GOV.UK Notify to send text +messages or emails. + +## Getting an API key + +An API key is like a password that lets your prototype talk to Notify. +Your prototype sends this key every time it asks Notify to do something. + +To get a key: +- sign into GOV.UK Notify +- go to the ‘API integration’ page +- click ‘API keys’ +- click the ‘Create an API’ button +- choose the ‘Team and whitelist’ option +- copy the key to your clipboard + +### Saving your key on your computer + +This will let your prototype talk to Notify while it’s running on your +computer. + +To save the key on your computer, run this command in your Terminal, in +the root folder of your prototype (where xxxxxxx is a key you’ve copied +from Notify): ```shell echo NOTIFYAPIKEY=xxxxxxx >> .env ```` -(where xxxxxxx is a key you’ve created in Notify). This creates a file -named `.env` which contains your API key. +This adds the API key to the end of your `.env` file. Your prototype +will load the key from your `.env` file. + +### Saving the key on Heroku + +This will let your prototype talk to Notify while it’s running on +Heroku. + +To save the key on Heroku, go to the settings page of your app, click +‘Reveal config vars’ and fill in the two textboxes like this (where +xxxxxxx is the key you’ve copied from Notify): + +KEY | VALUE +---------------|---------- +`NOTIFYAPIKEY` | `xxxxxxx` -To set it on Heroku, go to the settings page on your app, click -‘reveal config vars’ and enter NOTIFYAPIKEY and the value of the key -in the two boxes. +### Keeping your key safe + +It’s really important that you keep your key secret. If you put it in +the `.env` file it’s safe – that file isn’t published on Github. If you +do accidentally publish your key somewhere you must sign into Notify and +revoke it. + +## Add the Notify code to your prototype Add this code to the top of routes.js: + ```javascript var NotifyClient = require('notifications-node-client').NotifyClient, notify = new NotifyClient(process.env.NOTIFYAPIKEY); @@ -19,30 +71,66 @@ var NotifyClient = require('notifications-node-client').NotifyClient, `process.env.NOTIFYAPIKEY` is a special kind of variable that Node pulls from the environment your prototype is running in. -*** +## Sending your first email + +Make a page with a form to collect the user’s email address. For +example: +``` +{% from "input/macro.njk" import govukInput %} + +
+ + {{ govukInput({ + label: { + text: "Email address" + }, + id: "emailAddress", + name: "emailAddress" + }) }} -Make a page to collect the phone number or email address. This page -needs a textbox called 'email', to match req.body.email below, eg - + -You can change it to something else, eg `phoneNumber`, but you need to -change it in the code below as well. +
+``` + +Save this page as `email-address-page.html`. -This code goes at the bottom of routes.js: +Then add this code at the bottom of routes.js: ```javascript -router.post('/page-with-email-or-phone-input', function (req, res) { +// The URL here needs to match the URL of the page that the user is on +// when they type in their email address +router.post('/email-address-page', function (req, res) { notify.sendEmail( - // this long string is the template ID, get it from Notify - '24a8b897-2de9-4a9f-a2db-b6ef682f799a', - req.body.email, - {} + // this long string is the template ID, copy it from the template + // page in GOV.UK Notify. It’s not a secret so it’s fine to put it + // in your code. + 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', + // `emailAddress` here needs to match the name of the form field in + // your HTML page + req.body.emailAddress ); - // This URL can wherever you want to send people to after the - // emailhas been sent + // This is the URL the users will be redirected to once the email + // has been sent res.redirect('/confirmation-page'); }); ``` + +### Testing it out + +Now when you type your email address into the page and press the green +button you should get an email. You should also be able to see the email +you’ve sent on the GOV.UK Notify dashboard. + +Because your account is in trial mode you’ll only be able to send emails +to yourself. If you’re doing user research you can add the participants +email addresses to the ‘whitelist’ in GOV.UK Notify. This will let you +send them emails too. You’ll need to collect their email addresses and +get consent to use them before doing your research. + +## More things you can do with GOV.UK Notify + +The complete documentation for using the GOV.UK Notify API is here: https://github.com/alphagov/notifications-node-client#govuk-notify-nodejs-client From 7900a7afc1513c45856511cff965c19a3df87c17 Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Thu, 4 Oct 2018 09:51:40 +0100 Subject: [PATCH 3/9] Remove duplicate send/sent --- docs/documentation/using-notify.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/documentation/using-notify.md b/docs/documentation/using-notify.md index 313b408dfe..652fbc80c9 100644 --- a/docs/documentation/using-notify.md +++ b/docs/documentation/using-notify.md @@ -2,7 +2,7 @@ You can use GOV.UK Notify to send text messages or emails when users interact with your prototype. For example you could send users a -confirmation email sent at the end of a journey. +confirmation email at the end of a journey. ## Sign up for a GOV.UK Notify account From f0a0601e9724ef81508b8074d6bceaac519a9a27 Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Thu, 4 Oct 2018 10:01:28 +0100 Subject: [PATCH 4/9] Remove use of shell redirection to save key --- docs/documentation/using-notify.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/documentation/using-notify.md b/docs/documentation/using-notify.md index 652fbc80c9..d40ea0523d 100644 --- a/docs/documentation/using-notify.md +++ b/docs/documentation/using-notify.md @@ -30,14 +30,15 @@ To get a key: This will let your prototype talk to Notify while it’s running on your computer. -To save the key on your computer, run this command in your Terminal, in -the root folder of your prototype (where xxxxxxx is a key you’ve copied -from Notify): +To save the key on your computer, add this line to the end of the `.env` +file in your prototype (where `xxxxxxx` is the key you’ve copied from +Notify): ```shell - echo NOTIFYAPIKEY=xxxxxxx >> .env + NOTIFYAPIKEY=xxxxxxx ```` -This adds the API key to the end of your `.env` file. Your prototype -will load the key from your `.env` file. +Your prototype will load the key from your `.env` file. If you don’t +have a `.env` file then run your prototype (with the `npm start` +command) and it will create one for you. ### Saving the key on Heroku From c5d8516adb796bc5739c72543ff69688f5d8875e Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Thu, 4 Oct 2018 10:01:51 +0100 Subject: [PATCH 5/9] Capitalise GitHub --- docs/documentation/using-notify.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/documentation/using-notify.md b/docs/documentation/using-notify.md index d40ea0523d..080e62ada2 100644 --- a/docs/documentation/using-notify.md +++ b/docs/documentation/using-notify.md @@ -56,7 +56,7 @@ KEY | VALUE ### Keeping your key safe It’s really important that you keep your key secret. If you put it in -the `.env` file it’s safe – that file isn’t published on Github. If you +the `.env` file it’s safe – that file isn’t published on GitHub. If you do accidentally publish your key somewhere you must sign into Notify and revoke it. From eac9a31d366c970ad7eef2a8bd2e78ddb731d065 Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Thu, 4 Oct 2018 10:02:22 +0100 Subject: [PATCH 6/9] Remove unneeded explanation of variable --- docs/documentation/using-notify.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/documentation/using-notify.md b/docs/documentation/using-notify.md index 080e62ada2..099a7733d4 100644 --- a/docs/documentation/using-notify.md +++ b/docs/documentation/using-notify.md @@ -69,9 +69,6 @@ var NotifyClient = require('notifications-node-client').NotifyClient, notify = new NotifyClient(process.env.NOTIFYAPIKEY); ``` -`process.env.NOTIFYAPIKEY` is a special kind of variable that Node -pulls from the environment your prototype is running in. - ## Sending your first email Make a page with a form to collect the user’s email address. For From 531f95d98ca226da98df24638c79d86e1eed72f3 Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Thu, 4 Oct 2018 10:10:12 +0100 Subject: [PATCH 7/9] Use HTML not macro for form example --- docs/documentation/using-notify.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/documentation/using-notify.md b/docs/documentation/using-notify.md index 099a7733d4..2f261fbcc5 100644 --- a/docs/documentation/using-notify.md +++ b/docs/documentation/using-notify.md @@ -74,21 +74,27 @@ var NotifyClient = require('notifications-node-client').NotifyClient, Make a page with a form to collect the user’s email address. For example: ``` -{% from "input/macro.njk" import govukInput %} +{% extends "layout.html" %} -
+{% block content %} - {{ govukInput({ - label: { - text: "Email address" - }, - id: "emailAddress", - name: "emailAddress" - }) }} +
+
+ - +
+ + +
- + + + +
+
+{% endblock %} ``` Save this page as `email-address-page.html`. From aa9fbb3ab733600d9df93f426800bf40376d2579 Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Thu, 4 Oct 2018 10:14:38 +0100 Subject: [PATCH 8/9] Fix line telling people where to put routing code --- docs/documentation/using-notify.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/documentation/using-notify.md b/docs/documentation/using-notify.md index 2f261fbcc5..d4eed7de82 100644 --- a/docs/documentation/using-notify.md +++ b/docs/documentation/using-notify.md @@ -99,7 +99,8 @@ example: Save this page as `email-address-page.html`. -Then add this code at the bottom of routes.js: +Then add this code to `routes.js`, above the line that says +`module.exports = router`: ```javascript // The URL here needs to match the URL of the page that the user is on From 909b01ffd6d7e583a37107055172f344d6f47080 Mon Sep 17 00:00:00 2001 From: igloosi Date: Mon, 29 Oct 2018 12:57:52 +0000 Subject: [PATCH 9/9] Add CHANGELOG entry --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d8d99c30e..fda6d55009 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +# Unreleased + +- [#574 Add Notify integration guidance](https://github.com/alphagov/govuk-prototype-kit/pull/574) + # 8.2.0 New Features: