Target visitors by page variable

Use page-variable targeting when your own systems already know who a visitor is, for example a returning buyer, and you want a Grona campaign to show only to those visitors. Your site writes a value to a page variable, and a campaign created through the Public API shows its variation only when that variable holds the value you chose.

How it works

A campaign created with page-variable targeting names two things:

segmentId: the name of a page variable your site sets, for example audience_id.
segmentValue: the value that variable must equal for the visitor to see the variation, for example returning_buyer.

A visitor whose page has audience_id set to returning_buyer sees the variation. Any other value, or no value at all, and the visitor does not.

The full naming rules are in Page variables. In short, segmentId is letters, digits and underscores, not starting with a digit, up to 128 characters. segmentValue is 1 to 128 letters, digits, _, ., : or -.

Set up page-variable targeting

Decide the value in your own systems. Your data layer, tag manager or backend works out which value the visitor gets. Grona does not decide it. For example, your backend marks a signed-in shopper with earlier orders as returning_buyer.
Write the value to a page variable, as a string, before the Grona snippet. Put an inline script above the three lines of the Grona snippet at the top of <head>, so the value is there when the Grona script reads it.
```
<head>
  <script>
    window.audience_id = 'returning_buyer';
  </script>
  <link rel="preconnect" href="https://cdn.grona.ai">
  <script src="https://cdn.grona.ai/workspaces/YOUR_WORKSPACE_ID/antiflicker.js" data-grona-af-bg="#ffffff"></script>
  <script src="https://cdn.grona.ai/workspaces/YOUR_WORKSPACE_ID/main.js" async></script>
  
</head>
```
If the value comes from your backend, render it into that inline script on the server. If it comes from a data layer that is already on the page, copy it across in the same inline script, and convert it to a string:
```
<script>
  window.audience_id = String(window.siteData && window.siteData.audience || '');
</script>
```
Here window.siteData stands for whatever object your data layer fills in. It must already hold the value when this line runs.
Create the campaign through the Public API with the same name and value. Call it from your server, never from a browser, because the request carries your secret key.
Terminal window
```
curl https://api.grona.ai/v1/campaigns \
  -H "Authorization: Bearer $GRONA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Free delivery bar for returning buyers",
    "url": "https://shop.example.com/",
    "segmentId": "audience_id",
    "segmentValue": "returning_buyer",
    "externalId": "CMP-1024"
  }'
```
New campaigns start paused. The response includes each variation’s editUrl, to build the change in the visual editor, and its previewUrl. See Create campaigns from your platform for every field.
Preview, then set the campaign live. Open the variation’s preview link to check the change on your site, as in Preview and QA a variation. Preview ignores targeting, so it shows the variation whatever the page variable holds. When it looks right, set the campaign live:
Terminal window
```
curl -X PATCH https://api.grona.ai/v1/campaigns/CMP-1024/status \
  -H "Authorization: Bearer $GRONA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "live" }'
```

To change which visitors see the campaign later, send a new segmentValue or segmentId with PATCH /v1/campaigns/CMP-1024. A field you leave out is kept.

If the right visitors do not see the variation

Work through this checklist on a page where you expect the variation.

The variable is set late. If your code sets the variable after the Grona script has checked it, for example in a tag that fires after page load or after an asynchronous call to your backend, the visitor counts as not matching. Set it in an inline script above the Grona snippet.
The value is a number, not a string. If your values are numbers, write window.audience_id = '2', not window.audience_id = 2. Set the variable as a string that matches segmentValue exactly.
The name is reserved. Names the browser already defines on window, such as name, location, status, top, parent and history, are rejected when you create the campaign. Choose a name of your own, such as audience_id.
The name or value differs. Check spelling and letter case on both sides: the variable name in your page and segmentId, the value in your page and segmentValue.
The page does not match. Page-variable targeting adds to the campaign’s page targeting, it does not replace it. Check the campaign’s url, or its multi-page rule.
Another campaign wins the page. A campaign with a higher priority that enrols the visitor first stops this one from running. See Priority.
The campaign is paused. New API campaigns start paused.

You can check the variable in the browser console by typing its name, for example audience_id, on the page. It should print the value as a quoted string.

Next steps

Page variables

Create campaigns from your platform