Yoast SEO: announcing breaking API Changes

As we announced a while back, we’re working on real time content analysis functionality for Yoast SEO. While we wanted to preserve backwards compatibility, we’ve come to the conclusion that we won’t be able to for some filters. This means that some themes and plugins, who integrate with our page analysis functionality, will need to be updated. We will be releasing this update on November 2nd, 2015, so get ready!

Warning upfront: this post is geekier than the average post on yoast.com and doesn’t contain tips for your site.

From serverside to your browser

When Yoast SEO ran a page analysis on your content, this was all done on the server, not in your browser. This meant that when you had a plugin that added a block of text, the plugin would need to register with one of our filters and add that text to the analysis. Our move to a real time analysis means that we’re moving the entire analysis to your browser, instead of the server. This will probably make it easier for most of these plugins to interact with our analysis, but they’ll have to make changes.

The filters that will be removed are described in this GitHub issue. The most important filter, that most plugins and themes use, is wpseo_pre_analysis_post_content. If you use that filter, you will need to make changes as that filter is going away entirely.

We’ve devised a JavaScript plugin system, which we’ve described here. Other plugins can register with our plugin and modify the content and a few other variables. It’s important that you know the basic principles we had in mind when building this system so you understand why we did what we did.

Core requirements to the analysis

We want to make our analysis fast. Super fast. The main requirement we have is simple: when you go into the edit post or edit page screen, you usually have one main objective: editing content. Optimizing content, which is what you’d use our plugin for, is a secondary objective. So we want to make sure that A we don’t slow you down in reaching your primary objective and B we’re making the secondary objective accessible as quickly as possible after that.

Because of how a developer will need to “register” his plugin, the user will be able to see which plugin is causing the long load time. Also, if your plugin takes more than 5 seconds to get “ready”, we’ll ignore it.

The second requirement we have is consistency. For both speed and consistency reasons, we only allow synchronous modifications; if you need to fetch data from the server, we suggest you do it only once and cache the result. You can reload data in the background, and then trigger a reloaded event, which will reload the analysis. This makes sure the analysis continues to be real time and the results are consistent.

Register modifications

The modifications system we’ve defined is a lot like filters in WordPress, so you can think of it that way. It all happens purely in JavaScript space though. We’ve documented how these modifications work in the YoastSEO.js repo’s readme. We’ve also included an example plugin in the same readme.


If you have a shortcodes plugin, you need not worry. We will make a plugin ourselves and ship it with the first release that handles all (properly registered) shortcodes. This will actually be an improvement over how we currently handle shortcodes (right now we ignore them).

To sum it up

  • Real time page analysis is coming to Yoast SEO for WordPress on November 2nd.
  • wpseo_pre_analysis_post_content and a few other filters are going away, if you use that filter, update your code.
  • We will have a working beta on September 9th that you can test your code against. We might have it earlier, follow @YoastDev on Twitter for updates. Feel free to tweet your questions there too.
  • Make sure you follow the guidelines above as otherwise it might not work.

Start developing! If you run into issues, feel free to either open an issue on the YoastSEO.js repository or tweet at @YoastDev. We will try to help as best as we can.

Coming up next!

13 Responses to Yoast SEO: announcing breaking API Changes

  1. Thi4ago
    Thi4ago  • 9 years ago

    Yoast SEO plugin best of all time

  2. Ciprian
    Ciprian  • 9 years ago

    Will there be a switch to toggle real time on and off?

  3. Mariëlle
    Mariëlle  • 9 years ago

    Dear Joost,
    While I’m sure you have our best interest at heart, I can’t help but wondering why you are telling us all this complicated stuff?
    It’s really only for developers. I don’t have a clue what you’re saying, but I do get the feeling that this update is possibly going to present a problem and you’re putting that problem on OUR plates (our = website owner; and not all website owners are developers).
    You should communicate this change to all theme developers and plugin developers. THEY need to change something (possibly).

    • Joost de Valk

      Hi Mariëlle,

      it’s indeed aimed at developers, of which we support tens if not hundreds of thousands. The fastest way for us to reach them is by posting here. We’re not putting anything on your plate: if you’re not a developer, you’re not the intended audience of this post.

      This is why added the warning on top:

      Warning upfront: this post is geekier than the average post on yoast.com and doesn’t contain tips for your site.

      So no need to stress. Just wait and maybe point any theme and plugin developers you know at this post.

  4. Toon
    Toon  • 9 years ago

    I’m puzzled…
    I’m using Advanced Custom Fields (ACF) for a lot of pages/posts on websites, and most of the time I ignore (or even switch off) the main content area of a post or page.
    This way I can create a solid and user friendly environment for users to enter their specific content and assets (images etc.). This approach relies heavily on the ‘wpseo_pre_analysis_post_content’, because that’s the only way to get Yoast analyse the content from the different ACF fields.
    What does this mean for me as a site-developer when this filter is to be removed. Do I have to take specific actions or can I rely completely on your new browser approach and keep working with ACF, meaning that if fields are filled with content (when editing a post or page) they are being analysed.

    • Joost de Valk

      You wil need to write a bit of code that embeds a JavaSript plugin, and that JavaScript plugin should grab the content of the several form fields.

  5. aaron kronis
    aaron kronis  • 9 years ago

    This is great Joost! I hope it all works, perhaps you can partner with obi worldphone and make a better wordpress app that we can use anywhere.

  6. Sally
    Sally  • 9 years ago

    I have no idea what any of this means – I just created a website that I had hoped would be user friendly to a novice and apparently it isn’t. Now what do I do?

  7. Kenny
    Kenny  • 9 years ago

    Thanks Dominik, will give them a look around.

  8. Anh Tran
    Anh Tran  • 9 years ago

    This is a big change and it breaks my new extension of Meta Box for Yoast SEO content analysis (https://metabox.io/plugins/meta-box-yoast-seo/). The extension is new (created just 1 week ago) and now I have to look into your JS code to find a way to make it work with new API. I hope you can write a tutorial showing how to migrate from old API to the new one.


  9. Spafford Ackerly
    Spafford Ackerly  • 9 years ago

    Thanks for the heads up! Unfortunately, I the post leaves me a bit perplexed, as I am not a developer, and I don’t have a clue which plugins on my sites use the wpseo_pre_analysis_post_content filter. Is there a way to find out? Should I be concerned? Thanks!

  10. Kenny
    Kenny  • 9 years ago

    Hi Yoast dev, This sounds great… speed is always important.
    I am taking a fat chance here. Reading through lots of your material and so on, I have been wanting to ask a question. This is really the only way I could find to bring this up (contact policy).
    The area surrounding the beginning of a site in WP can be a source of confusion (like I have a redirect problem on landing page which I have no idea how to fix… but it is signifigantly slowing down the load).
    MY humble suggestion for yoast… why not a fee for question type arrangement… beginners don’t want site review yet and making sure that you start right, stops lots of problems down the line.
    Beginning expenses are an issue, so I’m thinking a pay for question policy, obviously where it might be a direction or general type question would be nice?
    Hope this works for reply.
    Thanks for all you great information.

    • Dominik Heinz
      Dominik Heinz  • 9 years ago

      Hey Kenny,

      I absolutly know what you mean.
      The Yoast Team does great work with building there Plugins and giving support for them. I think handling all the questions around get started with WP might not be there focus right now.

      You should try http://wpcurve.com/
      They help you fix your problems with WP and they explain everything if you want them to. I use wpcurve fot 2 projects right know and I’m impressed with there work.

      Have a nice day,