> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.omegatheme.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Set up Blockify on a Hydrogen store

## Overview

Blockify's app embed only works on Online Store themes. If your store runs on Shopify Hydrogen (a custom-built "headless" storefront), connect it in **Integrations > Hydrogen (headless)** so the rules you already set in Blockify (countries, IP addresses, VPNs, bots) protect it too. You create a key in Blockify, save it in your Shopify admin, and your developer adds two small pieces of code to the storefront.

## What you'll learn

* [How it works](#2-how-it-works)
* [Before you start](#2-before-you-start)
* [Create your API key in Blockify](#2-create-your-api-key-in-blockify)
* [Save the key in Shopify](#2-save-the-key-in-shopify)
* [Add Blockify to your storefront code](#2-add-blockify-to-your-storefront-code)
* [Deploy and check that it works](#2-deploy-and-check-that-it-works)
* [Choose a fail mode](#2-choose-a-fail-mode)
* [Change or replace your key](#2-change-or-replace-your-key)
* [Turn Hydrogen protection off](#2-turn-hydrogen-protection-off)
* [Troubleshooting](#2-troubleshooting)
* [Who can use this feature?](#2-who-can-use-this-feature)
* [FAQs](#2-faqs)

## How it works

Your store asks Blockify before it shows a page. Real shoppers see your store as usual. Visitors that your rules block see your Blockify block page, or are redirected, the same as on an Online Store theme.

![](https://storage.crisp.chat/users/helpdesk/website/-/8/3/8/3/8383e5404a31c000/set-up-blockify-on-a-hydrogen-_5asrp1.png)

## Before you start

| You need | Why |
| ---- | ---- |
| A paid Blockify plan | Hydrogen protection is not available on the Free plan |
| A Hydrogen store hosted on Shopify Oxygen | This is the usual setup. A store on another host needs one extra option, described in the code section below |
| Someone who can edit your store's code | The code and deploy steps need a developer. If you don't code, send them this article |
| About 30 minutes | Most of that time is the developer's deploy |

You do the parts in Blockify and in your Shopify admin. Your developer does the code part once.

## Create your API key in Blockify

1. In your Shopify admin, open **Apps > Blockify** and go to **Integrations**. Click **Set up** on the **Hydrogen (headless)** card. If you don't see the card, click the link **Using a headless storefront? Set up Blockify for Hydrogen** at the bottom of the page.

![](https://storage.crisp.chat/users/helpdesk/website/-/8/3/8/3/8383e5404a31c000/image_18u9m6b.png)

2. In the **API key** card, click **Generate key**.

![](https://storage.crisp.chat/users/helpdesk/website/-/8/3/8/3/8383e5404a31c000/set-up-blockify-on-a-hydrogen-_1gqfntn.png)

3. In the **Your API key** window, click **Copy key** and keep the key for the next section. Creating your first key also ticks **Enable headless protection** for you.

![](https://storage.crisp.chat/users/helpdesk/website/-/8/3/8/3/8383e5404a31c000/set-up-blockify-on-a-hydrogen-_1rwg9mp.png)

| Important: Blockify shows the key only once. Treat it like a password and never send it to anyone, including our support team. If you lose it, see [Change or replace your key](#2-change-or-replace-your-key).

4. Leave **Fail mode** on **Open — recommended**. See [Choose a fail mode](#2-choose-a-fail-mode) if you want to know what the other option does.

## Save the key in Shopify

1. In your Shopify admin, go to **Sales channels > Hydrogen** and open your storefront.
2. Open **Storefront settings > Environments and variables** and click **Add variable**.
3. Fill in the variable:

| Field | Value |
| ---- | ---- |
| Key | `BLOCKIFY_HEADLESS_KEY`, typed exactly like this |
| Value | The key you copied from Blockify |
| Secret | Turned on |
| Environments | Production. Add Preview too if you test there |

4. Save the variable.

## Add Blockify to your storefront code

This section is for your developer. Every snippet below is also on the Blockify **Hydrogen (headless)** page under **Install**, with a copy button and your store address already filled in.

![](https://storage.crisp.chat/users/helpdesk/website/-/8/3/8/3/8383e5404a31c000/set-up-blockify-on-a-hydrogen-_eqwx5q.png)

1. In the storefront project, install the Blockify package:

```
npm i @blockify-fraud/hydrogen --save-exact
```

2. Wrap the handler in `server.ts`. Keep your existing handler as it is and pass it to `withBlockify`:

```
// server.ts
import { withBlockify } from '@blockify-fraud/hydrogen';

export default withBlockify(
  {
    async fetch(request: Request, env: Env, executionContext: ExecutionContext): Promise<Response> {
      // ...your existing Hydrogen handler, unchanged...
    },
  },
  { shopDomain: 'your-store.myshopify.com' },
);
```

`shopDomain` is your `.``myshopify.com` address in lowercase. Do not use your custom domain here.

| Tip: Is your store hosted somewhere other than Shopify Oxygen? Also pass the `getBuyerIp` option so Blockify receives each visitor's real IP address. The package README explains how.

3. In `app/root.tsx`, render the Blockify widget once in your layout. It adds Blockify's content protection, such as right-click and copy blocking, to your pages:

```
import { BlockifyWidget } from '@blockify-fraud/hydrogen/client';

<BlockifyWidget />

// If your Content Security Policy uses a nonce:
<BlockifyWidget nonce={nonce} />
```

The widget starts only after a visitor accepts cookies. It reads that choice from Shopify's cookie banner, which the standard Hydrogen templates already load (`<Analytics.Provider consent>`, or `<ShopifyScripts consent>` on Hydrogen 2026.10).

## Deploy and check that it works

1. Deploy your store the way you normally do.

| Important: Deploy again every time you add or change the key. Shopify applies a new variable only to new deployments. If you skip this, your store runs normally but Blockify is not protecting it.

2. Find your own IP address by searching "what is my IP".
3. In Blockify, add a temporary rule that blocks that IP address.
4. Open your live store in a private browser window. You should see your Blockify block page.
5. Delete the temporary rule and reload. Your store shows again.
6. Open **Analytics** in Blockify. Your visits appear in the visitor log within a few minutes.

| Tip: Test on your deployed store. A storefront running on your developer's computer reaches Blockify as a placeholder visitor, so a rule aimed at your own IP address or country never matches there.

If you still see your store while the rule is on, go to [Troubleshooting](#2-troubleshooting).

## Choose a fail mode

**Fail mode** only matters in the rare moment your store cannot reach Blockify.

| Fail mode | What visitors see at that moment | Best for |
| ---- | ---- | ---- |
| **Open — recommended** | Your store, as normal | Almost every store. Sales never stop because of Blockify |
| **Closed** | A "Service temporarily unavailable" page | Stores that would rather pause than let anyone in unchecked |

A missing or wrong key never takes your store down. The store runs unprotected until the key is fixed.

## Change or replace your key

1. On the Blockify **Hydrogen (headless)** page, click **Rotate key**, then **Rotate now**, and copy the new key.

![](https://storage.crisp.chat/users/helpdesk/website/-/8/3/8/3/8383e5404a31c000/set-up-blockify-on-a-hydrogen-_1kqtaeu.png)

2. In your Shopify admin, replace the value of `BLOCKIFY_HEADLESS_KEY` with the new key, then deploy again.

The old key keeps working for 24 hours, so your store stays protected while you deploy.

| Important: If you rotate a second time within those 24 hours, the oldest key stops working immediately.

If you lost your key, rotate it the same way. A key cannot be shown again after you close the window.

## Turn Hydrogen protection off

Untick **Enable headless protection** on the Blockify **Hydrogen (headless)** page. Your store keeps working without Blockify. To remove Blockify completely, your developer removes `withBlockify` and `<BlockifyWidget />` from the code and deploys.

## Troubleshooting

| What you see | What to check |
| ---- | ---- |
| The test rule does not block you | **Enable headless protection** is ticked. You are on a paid plan. `BLOCKIFY_HEADLESS_KEY` is saved for Production and you deployed after saving it. `shopDomain` is your `.``myshopify.com` address in lowercase. Changes you make in Blockify take up to a minute to apply |
| Your whole store shows "Service temporarily unavailable" | Switch **Fail mode** to **Open — recommended**, then contact us |
| Shoppers can't complete checkout | Turn off Blockify's checkout protection and contact us right away |
| Right-click or copy protection does nothing | Accept the cookie banner first, then reload. If your store has no cookie banner, ask your developer to add Shopify's banner as described in the code section |
| No visits in **Analytics** | Wait a few minutes, then check the same items as in the first row |
| A real shopper is blocked | Open **Analytics**, find the visit and the rule that blocked it, then change the rule or add the shopper to a whitelist rule |
| "Too many requests" for many people in one office or network | Contact us with the time it happened and that network's IP address |

## Who can use this feature?

Available on every paid Blockify plan. It is not included in the Free plan.

## FAQs

1. **Will this slow down my store?**
Blockify adds one quick check before a page is shown, and shoppers shouldn't notice it. With **Fail mode** on **Open — recommended**, your store never waits on Blockify for long.

2. **Does it work with Hydrogen 2026.10?**
Yes, and with earlier Hydrogen versions.

3. **Do I also need the Blockify app embed?**
No. The app embed is for Online Store themes. A Hydrogen store only needs the steps in this article.

4. **Where do I get help?**
Chat with us in the Blockify app. Send your `.``myshopify.com` address, your store URL, the time the problem happened and a screenshot. Never send us your API key. We never need it.