Site Connector & WordPress Plugin

The Site Connector links a client's website directly to RankNest. With the RankNest WordPress plugin installed on the site, the connector collects page data. Turn on auto-implementation and RankNest also writes approved internal link recommendations into post content for you, instead of you editing every page by hand.

Where to find it

Site Connectors are per client. Open the client's Settings, go to the Integrations tab, and scroll to the Site Connector section.

How to create a connector

1. Click Connect Site (or Add Connector if one already exists).
2. Enter the client site's Domain (for example example.com).
3. Pick a Connector Type:
   • WordPress Plugin for a WordPress site. Read and write, with changes applied automatically. Requires WordPress 5.6 or newer.
   • Custom-Coded Site for anything hand-built (Next.js, Astro, a React app). Nothing is installed on the site; approved changes collect in a queue you apply in your own codebase. See Custom-coded sites below.
4. Click Create Connector.

A Connector Created Successfully panel appears with the connector's Site Key and a copy button.

How to install the RankNest WordPress plugin

1. Click Download WordPress Plugin on the created panel (also available later as Download Plugin (.zip) in the connector's setup instructions).
2. In the WordPress admin, go to Plugins > Add New > Upload Plugin.
3. Upload the downloaded ZIP file and activate it.
4. Open RankNest Connector in the WordPress left sidebar.
5. Paste your Site Key and click Save.
6. Optionally, enable auto-implementation to allow RankNest to add internal links to the site (see below).

Back in RankNest, click Verify on the connector row. If the plugin is set up correctly, the connector moves out of Pending; if not, the result panel lists what to check.

Enabling auto-implementation with a WordPress Application Password

To let RankNest write approved link recommendations into post content, the connector needs WordPress credentials. This is optional. Without it, the connector still reads page data.

1. In WordPress, go to Users → Profile → Application Passwords and create an application password. An application password is a purpose-made login token for one app; it is not your normal WordPress password.
2. In RankNest, on the connector row, find WordPress REST Credentials (set once).
3. Enter the WordPress Username and the Application Password.
4. Click Save Credentials. The password is stored encrypted, and RankNest runs a verification automatically.

Once saved, the row shows the password's last four characters. Re-enter a new one at any time to rotate it. The connector row then shows a Write access label. For how recommendations are reviewed and marked done, see Implementing Recommendations.

Queued link changes come from the Linking Plan: the Push to Site button on a recommendation card adds the link to this connector's queue, and the connector applies it to the site. See Implementing Recommendations for how pushing works.

The plugin works alongside Yoast SEO, Rank Math, and AIOSEO, and creates a revision before any content change so every edit can be rolled back in WordPress.

Pushing SEO test metadata

With plugin v1.12 or newer installed, starting an SEO test can also push the test's title and meta description straight to the site. When the client has a verified WordPress connector with saved credentials, the Start Experiment dialog shows an Apply title & meta to the site via the Site Connector checkbox (ticked by default). Leave it ticked and the variant's values are queued at Start and written into the site's SEO plugin within about 5 minutes; untick it to keep applying the change yourself.

With plugin v1.15 or newer, tests that change the H1 heading are pushed too. The heading is content, not SEO plugin metadata, so the plugin replaces it where it actually lives: in the page content (Classic editor, block editor, and shortcode builders like Divi), or in the WordPress page title when the theme renders that as the H1. A revision is created first, so the change can be rolled back from the WordPress editor. Elementor pages are the exception: their content lives outside the normal WordPress content field, so the push reports a clear failure and you change the H1 in Elementor yourself. If the page was crawled with no H1 at all, there is nothing to find and replace, and RankNest tells you at Start that the H1 change needs applying manually.

A few things to know:

• The values are written into whichever SEO plugin the site runs (Yoast SEO, Rank Math, or All in One SEO), so the change lands exactly where you would have typed it. On a site with no SEO plugin, only the description can be stored; a title change is rejected rather than overwriting the visible page title.
• The same auto-implementation toggle in the plugin settings that governs link pushes governs metadata pushes. If it's off, the push fails with a clear message.
• The previous title and description are captured with each push, so you can restore them by hand if needed. If your SEO plugin used a template (like %title% %sep% %sitename%), the push replaces it with the test's literal text; the captured previous value preserves the template for restoring.
• A Restore Original recovery test goes through the same Start flow, so the original values can be pushed back the same way.
• If the site is still on plugin v1.11 or older, the push fails with a message telling you to download and install the updated plugin from this page. Link pushes keep working either way.

Custom-coded sites

A WordPress site keeps its content in a database behind a live API, so RankNest can write to it directly. A hand-built site is different: the paragraph you want to edit is source code, and changing it means editing a file and redeploying. RankNest cannot do that for you, so a Custom-Coded Site connector works as a queue instead.

Nothing is installed on the site. When you push a recommendation from the Linking Plan, or start an SEO test with Apply via connector ticked, the change lands in this connector's queue. You then apply it in your own codebase and report it done, which marks the recommendation implemented in RankNest.

To work the queue you need an access token set as RANKNEST_TOKEN in the site's repository or CI. Click Create token for this site on the connector card: the token it mints is scoped to this one connector, so it can list and complete this site's queue and nothing else. That makes it safe to store in a repo the client's own developers can read.

An agency-wide Personal Access Token also works, but it sees every client in your account. Keep those on machines you control, never in a client repo. Then, in the site's repository:

npx ranknest site-connectors queue <connector-id> --status queued

Make each change in your source files, commit, and report the outcome:

npx ranknest site-connectors queue-update <connector-id> <item-id> --status completed --revision-id <git-sha>

--revision-id is optional and free-form. A commit SHA is the useful thing to put there, since it tells you later exactly which deploy carried the change.

Expand the connector's row at any time to see its ID and both commands. While items are waiting, recommendation cards in the Linking Plan show Awaiting pickup rather than Queued, because nothing will move them until you do.

Connector health

Each connector row shows its current state at a glance:

• Status badge: Pending (created, not yet detected on the site), Verified (detected), Active (sending data), Inactive (paused), or Revoked.
• Last data: the date the connector last reported.
• Page count: how many pages the connector has synced.
• Write access: shown when auto-implementation credentials are in place.

Use the pause button to temporarily deactivate a connector and the play button to reactivate it. The delete (trash) button permanently revokes the connector and stops all data collection.

Once a connector has reported pages, a Sync pages button appears on its row. It promotes the collected pages into the client's newest link map right away. The same sync also runs automatically every hour, so the button is only needed when you don't want to wait.

Troubleshooting

Verification fails after installing the plugin. Confirm the plugin is activated, the Site Key was pasted exactly, and the Domain on the connector matches the site's real domain. The verification result panel lists the specific checks that failed.

Verification fails even though the Application Password looks correct. Run this from a terminal first, substituting your own domain, username, and application password. It tells you which of two very different problems you have:

curl -u "USERNAME:APP PASSWORD" https://example.com/wp-json/wp/v2/users/me

• JSON describing your user. The credentials are fine and the problem is elsewhere. Check the plugin is activated and the connector Domain matches.
• incorrect_password. WordPress found the user and checked the password against that user's application passwords, and none matched. Create a new application password and re-enter it.
• rest_not_logged_in. WordPress never evaluated the credentials at all. This is the confusing one, and it has two causes. Work through them in order.

Cause 1, by far the most common: the application password belongs to a different user. In WordPress, Users → Profile always opens the profile of whoever is logged in. If you were signed in as yourself and created the application password there, it is attached to your account, not to the account whose username you entered in RankNest.

Check by going to Users → All Users, clicking Edit on the exact username you gave RankNest, and scrolling to Application Passwords. If that table is empty, this is your problem. Create one from that page.

Cause 2: the host does not pass the Authorization header to PHP. This affects some CGI and FastCGI setups. Add this to the top of the site's .htaccess, above the # BEGIN WordPress block:

CGIPassAuth On

Most WordPress installs already carry the companion rewrite rule inside the # BEGIN WordPress block, so CGIPassAuth On is usually the only line you need. If the site returns a 500 error immediately after saving, your Apache predates this directive; remove the line and the site recovers. On nginx or LiteSpeed, or behind a firewall such as Sucuri or Cloudflare, ask your host to forward the Authorization header to PHP.

The connector shows no recent data. Check the status badge. An Inactive connector is paused; press play to reactivate. If it is Active but stale, verify the plugin is still activated on the WordPress site.

Auto-implementation isn't available. The connector needs saved WordPress credentials. Add the username and application password under WordPress REST Credentials and click Save Credentials.

Related

• Implementing Recommendations
• Client Integrations
• Linking Plan Overview