Embed Surfer guidelines in your CMS

​

Availability

• Your editor runs in a browser, on an HTTPS page. The panel’s request for storage access is refused on a page that is not served over HTTPS.
• The writer is signed in to Surfer in the same browser, to link or create a Content Editor from the panel. A page whose permalink already resolves shows its guidelines either way (Access and sharing).
• The browser lets Surfer use its cookies inside your page: third-party cookies allowed for app.surferseo.com, or storage access granted when the panel asks. No browser extension is needed; Sign in and cookies has the details.
• The writer’s Surfer account includes Content Editors.

​

Add the library

<script>
  ;(() => {
    if (window.surferGuidelines !== undefined) return

    window.surferGuidelines = {
      init(...args) {
        window.__sg_in = args
      },
      setHtml(...args) {
        window.__sg_sh = args
      },
      initWithOptions(...args) {
        window.__sh_gi = args
      },
    }

    const libTag = document.createElement('script')
    libTag.async = true
    libTag.src = 'https://app.surferseo.com/static/surfer_guidelines_1_x_x.js'
    document.body.appendChild(libTag)
  })()
</script>

​

Add a container and start the panel

<div id="editor-page">
  <textarea id="editor" placeholder="Write the article as HTML"></textarea>
  <div id="surfer-guidelines"></div>
</div>

<script>
  window.addEventListener('load', () => {
    const { $iframe, setPermalink, setHtml } =
      window.surferGuidelines.initWithOptions({
        partner: 'your-cms',
        onContentScoreChanged(score) {
          console.log('Content Score', score)
        },
      })

    document.getElementById('surfer-guidelines').appendChild($iframe)

    setPermalink('https://your.cms.com/draft/some-draft-id')

    const editor = document.getElementById('editor')
    setHtml(editor.value)
    editor.addEventListener('input', () => setHtml(editor.value))
  })
</script>

• initWithOptions creates the iframe and returns it together with the functions that drive it. The iframe is not in the page until you append it.
• partner names your integration to Surfer. Use one short identifier for your product.
• setPermalink tells the panel which document this is; until it receives one, the panel stays on its loading state.
• setHtml sends the article. Call it once at start and again on every change.
• onContentScoreChanged runs each time the SEO score changes.

#editor-page {
  display: flex;
  height: 100vh;
}

#editor {
  flex: 1;
}

#surfer-guidelines iframe {
  width: 400px;
  height: 100%;
  border: 0;
}

​

What you see

​

Send the article’s HTML

• When: once at start and after each edit. Each call posts the whole HTML to the panel, so debounce the call if your editor fires on every keystroke.
• After setPermalink: call setHtml again, because a new permalink drops the HTML the library holds (The handle).

​

Next steps

• Access and sharing: the signed-in and shared modes, getting a permalink for an existing Content Editor from the API, and sharing tokens.
• JavaScript API: every option, callback, and handle function with its payload.

​

Troubleshooting