Prepare Links with CivicEngine

Introduction:

 

CivicEngine products all require an address to show voters their most accurate information. Generally, voters enter their address into an embeddable widget to access the tool, but if their address is known, they can access the tool by clicking a prepare link like this: 


https://www.ballotready.org/w/prepare

address=332%20S%20michigan,%20chicago,%20IL,%2060605&utm_source=demo&default_locale=vi US-ballotready2” 


The above link has three parameters: address, utm_source, and default_locale. Using these parameters, the BallotReady engine will behave exactly like someone has entered through the widget and entered the address ‘332 S Michigan, Chicago IL’ and chosen the Vietnamese language option at a link with the utm_source parameter in the URL. Every time that link is clicked, it’ll create a new ballot record with those parameters, but with separate ballot_ids. 


Structure: 


The prepare link should be formatted like this: 

https:// + instance_url/w/prepare? address= + address input+ any optional parameters 


Your instance_url will be given to you by your onboarding manager, and will be the way to access your CivicEngine product without a widget or prepare link. The format the instance_urls follow is usually app.customername.civicengine.com. Go Ballot’s instance_url is app.goballot.civicengine.com


Parameters: 


These are the parameters you can build into your prepare link. Note that any prepare links will not pass any UTM codes from the page they are hyperlinked into, they will only pass the UTM codes built

into the link. The address parameter is the only required parameter and should always come first, immediately after the 

Parameter

User data 

field

Widget 

equivalent 

Notes

address 

address 

address 

required

first_name 

first_name 

data-input 

first-name


last_name 

last_name 

data-input 

last-name


email 

email 

data-input 

email


phone 

phone 

data-input 

phone


custom 

custom 

data-input 

custom-field

Custom dropdown field in the widget

utm_term 

utm_term 

data-utm-term 

Go Ballot should use this field to pass unique IDs

utm_source 

utm_source 

data-utm 

source


utm_medium 

utm_medium 

data-utm 

medium


utm_campaign 

utm_campaign 

data-utm 

campaign


utm_content 

utm_content 

data-utm 

content


default_locale 

locale 

data-default 

locale

Only functional if your tool is 

translation enabled.


Link Creation


You can create your link by inputting the following code into your browser’s console, substituting any of the parameters you wish: 


encodeURI('https://www.ballotready.org/w/prepare?address=332 S Michigan Ave, Chicago IL&first_name=Sandra&last_name=Smith&phone=888-888-8888&utm _term=demo_alloy_id') 


Passing UTM codes without a prepare link 


If you’d like to direct someone to the tool with a certain UTM code, but there’s no address you have for them, you can give them a link to your landing page with that UTM parameter in the URL and the UTM code will be passed through the widget, as long as there are no UTM parameters defined for that widget. More information about using UTM codes with the CivicEngine widget can be found here.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.