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: diff --git a/docs/documentation/using-notify.md b/docs/documentation/using-notify.md new file mode 100644 index 0000000000..d4eed7de82 --- /dev/null +++ b/docs/documentation/using-notify.md @@ -0,0 +1,141 @@ +# 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 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, add this line to the end of the `.env` +file in your prototype (where `xxxxxxx` is the key you’ve copied from +Notify): +```shell + NOTIFYAPIKEY=xxxxxxx +```` +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 + +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` + +### 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); +``` + +## Sending your first email + +Make a page with a form to collect the user’s email address. For +example: +``` +{% extends "layout.html" %} + +{% block content %} + +