Connectivity Test Removal, New Filters, Enhancements & Bug Fixes

Connectivity Test Removal

Starting from this version, the WordPress SDK no longer makes a connectivity test (aka ping.json) to the Freemius API upon plugin/theme activation.

This now-obsolete feature, which was initially used to improve user experience (more on that down below) and later proved to be a cause for concern among users, is finally down and out.

For demonstration, I downloaded the latest version of TablePress, which uses Freemius, and manually updated the SDK to 2.5.4. Here’s what happens after activation:

Voilà 🎊 As you can see on Snitch, a plugin that monitors remote requests, no HTTP requests were made after plugin activation.

Why the SDK Had a Connectivity Test (The Backstory)

After launching the WordPress SDK, we quickly discovered that API connectivity could not be taken for granted. Whether it’s related to cURL misconfiguration, HTTPS or OpenSSL issues, firewalls, or regional ISP blockages, servers are sometimes unable to make remote requests.

After researching popular plugins with an opt-in component, we stumbled upon Jetpack. The plugin initiates a connectivity test immediately after activation. You can test it yourself:

Long story short, as this approach enabled us to resolve the challenge we were facing — along with the fact that Jetpack is a super popular plugin with millions of active installs and developed by Automattic — we decided to replicate this approach to make sure we didn’t show the opt-in to users who wouldn’t be able to opt-in anyway due to connectivity issues.

The connectivity test was also useful in identifying clock differences between the WP site and the API server, which is essential for security reasons. This allowed developers to limit the exposure of the SDK — or even turn it off completely — without the need to release a new version.

If you are a developer who has been using the moderation capabilities, make sure to read the next section.

Warning: Breaking Changes

By removing the connectivity test, the moderation capabilities had to be transitioned to SDK settings. So, if you are using the moderation section in the Developer Dashboard to activate Freemius only for new installs or you limit the number of installs, please make sure to add the new config.

So, for example, the settings to only show the opt-in for new installations looks like this:

'opt_in_moderation' => array(
    'new'       => 100,
    'updates'   => 0,
    'localhost' => true,
),

• 'new' (int | boolean): An integer from 0 to 100 to control the exposure percentage of the opt-in to new product installs. It also supports a boolean value. When set to true, then assume 100% exposure; if set to false, then no exposure at all. Defaults to true (as 100%) when not set.
• 'updates' (int | boolean): Exactly as the ‘new’ param, but controls the opt-in exposure for product updates (i.e., what % of websites will see the opt-in after upgrading to a new version with the Freemius SDK, when the previous version didn’t include the SDK).
• 'localhost' (boolean): Whether to show the opt-in on localhost sites. Default's to true if not set.

New Filters

You can now override the in-dashboard checkout URL across the entire SDK by using the 'checkout_url' filter. Or you can use the 'update_notice_checkout_url' to specifically set the checkout URL shown in the admin notice when a license has expired.

Enhancements & Bug Fixes

💡 We have improved the logic determining if WP is executed via an HTTP/S request, which resolves some PHP notices when WordPress gets executed via WP CLI or through an actual server cronjob with define('DISABLE_WP_CRON', true).

💡 Added support for Kinsta's new staging environment URL patterns.

🐞 Fixed the permissions state after upgrading to a paid version in anonymous mode.

🐞 Fixed the in-dashboard affiliate application form submission.

Why a Release Candidate And Not the Final Version?

SDK version 2.5.4 was thoroughly code reviewed and fully tested. While we have high confidence it's production-ready because the change is on the infrastructure level, it's inevitably of a higher risk. Along with the fact that many of the Freemius team are traveling to WordCamp Asia this week (meet us 🤝) and many of us will stay in Thailand for another week of vacation, we decided that it wouldn’t be responsible to release it as a final version before we're back in full capacity at our home offices with strong internet and the proper working environment to react promptly if/as needed.

Call For Testers

Dear Freemius partners, we need your help in testing the release candidate.

If you're using the SDK functions beyond the standard integration snippet, please verify your integration still works as expected.

If you have automated testing, please make sure to run your tests to verify those are still passing ✅ If you don't, you can still help by running sanity testing with the new SDK.

• Try out the activation experience, preferably both on a regular site and a multisite network.
• It would be great if you could also test the upgrade flow by replacing the SDK in an already active environment where the plugin/theme is active. If you're extra awesome, give it a try for both a free version of your product and its paid version.

WordCamp Asia 🌴

We're super pumped for WordCamp Asia. The team is flying to Bangkok from four continents 🗺 It’s an exciting opportunity to finally meet fellow “Freemians” face2face 😁 This was something that was planned a long time ago in 2020, but we all know how it ended 🤷‍♂️

We’re looking forward to hanging out with community members, catching up with friends, establishing new connections, and talking to plugin & theme developers and other product makers.

We are also eager to meet with freelancers, agencies, and anyone who’s building websites professionally, as we are looking for feedback on how we can make Freemius even more awesome for professional builders.

With that said…

Reduced Availability Until Feb 26th

Heads up, we're transitioning to maintenance mode for the next two weeks (until Feb 26th). We will keep providing support throughout the entire period, with a focus on pressing issues.

Supporting "Requires PHP", enhancing "Tested Up to" and PHP 8.1 compatibility improvements

Supporting "Requires PHP" in the readme.txt

WordPress supports having a special header Requires PHP in a plugin's readme.txt file. If this is present and the current web-host is not running a compatible PHP version WordPress blocks plugin updates.

Following feedback from our partners, we have added the same capability in our SDK and deployment strategy. If you include the Requires PHP header in your plugin's readme.txt file, the SDK will show an appropriate notice in the update page and will block update if needed.

Improvements to the "Tested up to" header

If the current WordPress version is a patch of the "Tested up to" version (e.g., 6.1.2 is a patch of 6.1), then our SDK will now detect it and will show that the plugin is compatible with it. This saves a false positive notice and also saves our partners from having to deploy a version just to bump a patched "Tested up to" header.

PHP 8.1 Compatibility improvements

We've found some compatibility issues with how FS_Admin_Menu_Manager was called when running our SDK with PHP 8.1. With this release, the issue has been fixed.

Added Missing Opt-Out Dialog Stylesheet

Patches version 2.5.1 by adding assets/css/admin/optout.css (and optout.css.map), a CSS stylesheet for styling the new opt-out permissions dialog.

PHP 8 Compatibility, Clone Resolution Out of Beta, Revamped Opt-In and License Activation, and Tons More!

All of the features and updates included in version 2.5.0-RC.1 (a release candidate) are now part of the SDK. If you are still on 2.4.x (or below), please take the time to review the previous release notes to familiarize yourself with the expected updates.

Here are 2.5.0-RC.1 highlights:

• Clone Resolution Mechanism
• Deactivation Feedback Form Snoozing
• User Assets Ownership Switch Resolution
• Fix of HTTP 404 Not Found (AKA ‘No Updates’)
• Fault Tolerance to Background Connectivity Issues

PHP 8 Compatibility

The new SDK version resolves all reported PHP 8 incompatibility issues and warnings 🐘

Clone Resolution Is Out of Beta

The Safe Mode & Clone Resolution mechanism introduced in 2.5.0-RC.1 is officially out of beta. In addition to the bug fixed during the beta period:

• The mechanism now properly supports multilingual websites.
• We improved the clone identification logic to cover more cases.
• The auto resolution was also significantly improved, reducing the number of manual interactions.

We’ve also introduced a new FS__RESOLVE_CLONE_AS flag, which allows you to programmatically guide the mechanism for resolving clones upon site replication. The flag can easily be added to a site’s wp-config.php (or functions.php) with one of the following values:

// A temporary duplication for the purpose of testing, staging, or development.
define( 'FS__RESOLVE_CLONE_AS', 'temporary_duplicate' );

// The new site is replacing the old one — this will migrate the license activation to the new site to resolve the clone.
define( 'FS__RESOLVE_CLONE_AS', 'new_home' );

// The cloned site is a new and different one — this will automatically activate the license on the new site to resolve the clone.
define( 'FS__RESOLVE_CLONE_AS', 'long_term_duplicate' );

Opt-In v.2.0

Following tons of feedback, we are excited to introduce the next generation of our opt-in screen 🎊

In addition to the slicker UI:

• The opt-in copy underwent a significant overhaul to better communicate the purpose of the opt-in screen as well as what can be expected when opting in.
• The permissions list was reviewed thoroughly to ensure it covers exactly what’s shared when opting in.
• We switched the framing of the copy from “How it helps developers” to “How it helps you” — “you” being the user installing the product. This helps to emphasize the user benefits of opting in.
• New tooltips were added to most permissions, adding more context to how sharing the info benefits users.
• To minimize confusion among users unaware of Freemius, we removed the Freemius logo from the opt-in screen. We updated the permissions micro-message to clarify that opting in means sharing the info with the product’s team. Basically, positioning Freemius as the opt-in facilitator and data processor.

‘Anonymous’ License Activation

Like the opt-in, the license activation also went through a similar UI and framing refresh. What’s even more exciting is that licenses can now be activated with a minimal data footprint. This means only sharing the essentials needed for Freemius’s license & updates delivery engine:

• Homepage URL
• Product version
• SDK version
• Whether the product is active (or uninstalled)

That’s it!

So anyone sensitive about privacy can easily expand the permissions list and toggle off the new Diagnostic Info permission. This skips the sharing of WordPress & PHP versions, and site language & title.

Thanks, Chris Wiegman, for providing your feedback on it!

User IP Sharing — No More!

After our CEO Vova Feldman participated in a live QA about Freemius, a concern was raised about sharing user IPs.

For context, the IP was used to identify users’ geolocation to help developers recognize which languages & regions their plugin/theme should be translated and tailored to. It can also be used for security purposes to flag suspicious activity and prevent impersonation.

Even though it was only shared with user consent upon opting in, we have re-evaluated the need for this data point and decided to remove it altogether:

https://github.com/Freemius/wordpress-sdk/pull/580/files

Along with the user IP removal, we’ve also stopped sharing the nickname of the opting in user — this was used as a placeholder when the user had an empty first and last name.

Thanks, Sean D., for bringing it to our attention!

Skip … Is Only for Skipping

When we launched Freemius in 2015, the WordPress.org repository didn’t have the active installs growth chart (which was recently back in the news after its removal). At the time, plugin and theme developers were “thirsty” to understand how efforts to improve their products impacted adoption. To solve this problem and give developers an accurate picture of their product usage, skipping the Freemius opt-in also sent an anonymous ping, which increased the product’s “skips” counter. Along with the Deactivation Feedback Form and some heuristics, we could offer an estimate of the product’s audience size.

Long story short: over the years, we realized the skips counter is far from accurate, unreliable, and prone to errors, which is why we’ve removed it from the new dashboard. Combined with the fact that some didn't like this behavior, the Skip button is just for skipping the opt-in now. That's it.

Improved Copy for Email Verification

The connection between the SDK and the Freemius API is secured with public/private keys and we manage a single entity per email address. If a person with the same email address has already opted in on another website, we have to make sure they are not impersonating by confirming the ownership of their address before sharing the keys with the website.

Following feedback (thanks, David McCan), we realized the email copy was confusing. We therefore revised the copy to clarify the purpose of the confirmation:

Granular Opt-Out Permissions

To make the opt-in permissions more flexible and allow users to pick and choose what they want to share, the team has introduced a brand new permissions management layer for free and paid products.

Clicking the Opt Out action link now opens a new dialog box where users can selectively choose which of the permissions they want to opt out from or keep sharing:

The granular permissions support new states that were not supported before. For example, a user can stay subscribed to receive email updates from the product team while opting out from sharing diagnostic info about their WordPress environment.

And here’s how it looks for paid products:

The new permissions layer comes with complementary events you can consume through a webhook:

install.extensions.opt_in

Occurs whenever a user opts in for sharing a website’s plugins & themes list after previously opting out from it.

install.extensions.opt_out

Occurs whenever a user opts out from sharing a website’s plugins & themes list after previously sharing it.

install.user.opt_in

Occurs whenever a user opts in for sharing their basic profile info after previously opting out from it.

install.user.opt_out

Occurs whenever a user opts out from sharing their basic profile info after previously sharing it.

You can find the complete events list here:

https://freemius.com/help/documentation/marketing-automation/events-webhooks/

Important:

• For consistency, starting from Jan 1, 2023, the events install.connected and install.disconnected will be renamed to install.site.opt_in and install.site.opt_out (correspondingly). So, if you “listen” to any of these events through a custom webhook, make sure to update the webhook to support the new event names before.
• If you are using Freemius’s MailChimp Integration, make sure to update your rules by unsubscribing a user from your lists when install.user.opt_out occurs, and optionally resubscribing them on install.user.opt_in.

New Actions to Further Customize the Opt-In Screen

We’ve introduced a new set of actions to enable more advanced (yet still structured) customization of the opt-in screen:

connect/before

For adding text or visual elements before/above the opt-in container.

connect/after

For adding text or visual elements after/below the opt-in container.

connect/before_message

For adding text or visual elements before/above the opt-in message header (within the ...

Version 2.4.5

• Updated translation files to fix placeholder issues in PHP 8.

2.4.4

• PHP 8.1 compatibility fixes.

Thank you @matczar for the PR 🙌

2.5.0-rc.2

Merge pull request #545 from Freemius/feature/2.5.0-rc.2-linear-secur…

2.4.3

Merge pull request #544 from Freemius/feature/security-fix-master-2.4.3

Security fix on top of master for 2.4.3 tag

2.5.0-RC.1 Is Ready for Testing: Clone Resolution, Deactivation Feedback UX Enhancements, Assets Mix-Up, and More

Call for Testers

Even though we ran thorough testing of all kinds (automated, manual, and regression tests), and while we feel pretty confident in the stability of 2.5.0, due to the complexity and amount of code changes & use-cases involved in this version, we decided to push it as a release candidate first.

"I want to be involved in testing - how can I help?"

Want to help us in testing? That's great and appreciated!

• If you are running a beta program, simply update the SDK to this RC and push a new version as a beta.
• If you are not running a beta program and know that some of your customers running cloned environments like staging to production, or using your plugin/theme with WaaS plugins like WP Ultimo, when they contact your support due to SDK issues you can send them a special version of your product with this SDK as it should solve their problems.

Regardless, if you try out the RC, whether you experience issues or, on the contrary, if it resolves the SDK problems your users were facing before, please let us know! Simply contact us via [email protected], open a GitHub issue, or use any other communication channel that is easiest for you - we want your feedback :)

Duplicate Websites and Clone Resolution

With the growing popularity of WaaS (WordPress as a Service) networks and hosting companies that provide 1-click staging to production deployment workflows, you’ve probably already dealt with customers complaining about unexpected issues when site duplication is involved.

In short, a clone is a website (or a subsite) that has a unique ID and pair of public/secret keys that were assigned by Freemius and are identical to the ID and keys of another website. You can learn more about clones, how they are typically created, and when, in this doc.

Inspired by Jetpack's UI, I’m excited to share that this SDK release comes with a fully-featured clone identification, management, and resolution mechanism. It’s a capability that’s been on the back-burner for quite some time, and I highly encourage you to familiarize yourself with the clone websites problem and how the WordPress SDK handles it to get the most out of the enhancement:

Deactivation Feedback Form UX Enhancements

Snoozing for Troubleshooters

While our deactivation feedback form offers a unique opportunity for users to provide feedback to product owners before they abandon, over the years we’ve heard complaints that users really hate the feature. After analyzing the feedback, we managed to attribute this sentiment specifically to the ‘troubleshooters’ segment.

Plugin updates are a common task that website maintainers have to deal with on a daily basis. Sometimes a plugin/theme update can go wrong due to conflicts, bugs, and incompatibilities, causing issues and unexpected errors on a site. Maintainers usually don’t dive into the code level, so the common troubleshooting process is to identify the cause of the problem with plugin deactivations and reactivations, followed by theme switching. Meaning, you need to deactivate the plugins one by one until the problem is resolved, then reactivate them individually and in the same order that they were deactivated. In theory, this should help isolate the ‘problematic’ plugin, but if it doesn’t uncover the issue then the next attempt should be a ‘theme switch’.

As the ‘footprint’ of themes and plugins that use our WordPress SDK grows, the deactivation feedback form adds an additional click to each deactivation. From there, reactivating a Freemius-powered plugin automatically redirects to the opt-in screen or to the plugin main settings page (based on the opt-in state), which adds another click to navigate back to the plugins page.

This means that just 5 plugins using Freemius on a site can potentially add 10 extra clicks — something that’s understandably annoying for troubleshooters. And when managing 20 sites, as an example, all those clicks accumulate over time, which explains why some maintainers really dislike the WordPress SDK.

Having understood the reasons behind the ‘hate’, we came up with a simple solution to relieve the ‘pain’ for troubleshooters and, hopefully, win some of their trust back.

The Feedback Form already displays an option that indicates a deactivation is temporary for troubleshooting. So, instead of just sending that feedback our way…

1. We now show an option to snooze the panel from one hour to 30 days.
2. Because we realize it doesn’t add any value to product owners, choosing to snooze skips sending feedback to Freemius altogether.
3. Finally, if the admin snoozes the form, the redirection will be off for the snoozed period.

Snoozing will only impact the current logged-in admin and will work across all Freemius powered plugins and themes installed on that website.

This improved UX can potentially save tons of clicks for ‘heavy’ troubleshooters, and we are excited to see the difference it will make.

Enable Deactivation with Empty ‘Other’ Feedback

To encourage users to submit feedback you can act upon, previously, when a user selected the ‘Other’ option in the deactivation feedback form, the ‘Submit & Deactivate’ button’s state was changed to disabled until the user entered some input to explain the ‘other’ reason.

It was brought to our attention that this UX was problematic because users read from top-left and some choose that option because they simply don't want to provide any feedback. I.E., if they choose that option before noticing there’s an option to ‘Skip & Deactivate’, it gives the impression that it’s impossible to deactivate the product without providing any feedback.
Now, when the ‘Other’ option is selected and the explanation box is empty, the button is enabled and labeled as ‘Deactivate’:

And, obviously, no data will be sent to our end because empty ‘Other’ feedback is useless.

Anonymous Feedback Default Checkbox State

If a user skipped the opt-in and chose to provide feedback using the deactivation feedback form, by default the feedback was not anonymous to allow you to contact the user if needed. This version of the SDK introduces a new filter so that you can control the default submission mode of the feedback form and change it to anonymous feedback by default, using the following:

my_fs()->add_filter( 'default_to_anonymous_feedback', '__return_true' );

User Assets Ownership Mix-Up — Gone!

A healthy percentage of WordPress plugin and theme purchases are made by ‘builders’, where eventually the project is handed over to their client. To facilitate the relationship, we offer a good amount of flexibility to allow changing ownership of account assets from one person to another.

Without diving into the technicalities, with the many millions of websites running our SDK, we stumbled upon several edge cases that unexpectedly mixed up assets between accounts. While these issues were infrequent, it’s painful for the customer, for you, and for us to fix.

If there was a contest for the most annoying and time-consuming issues, this one is the undisputed winner of 2020–2021 🏆 It’s also a good example of where giving too much flexibility without trying to foresee all of the use cases (and you never will) can cause more damage than good.

Not only did we add some restrictions in the backend to reduce the instances of the issue, the new WordPress SDK release enhances the Account’s email update experience with additional input from the user, and handles each case slightly differently:

Fix of HTTP 404 Not Found (AKA ‘No Updates’)

Some of you may have received support tickets where customers complained that the SDK is throwing errors and slowing the system down, typically with a complementary screenshot of an error from Debug Log (or other debugging plugins).

The HTTP errors were returned when there were no newer releases, which is the expected behavior of a proper RESTful API implementation when a resource doesn't exist.

Since it’s not trivial to understand that this behavior is expected until contacting us, and it generated unnecessary support tickets for you (and us), we have modified the HTTP response code to 200 to eliminate this confusion once and for all. This API change was already deployed several weeks ago, so there's a good chance you’ve noticed this type of complaint has disappeared.

Looking back, we now acknowledge we should have made that change much earlier. It's just that sometimes the ‘right’ technical thing isn’t ‘right’ for the end user.

Fault Tolerance to Background Connectivity Issues

A few weeks ago AWS had a temporary downtime. As we host our servers on Amazon, naturally, the downtime caused connectivity issues to our API server. The websites that their Freemius sync cron was executed during that period were added with a dismissible notice about the connectivity issue, causing a bunch of support inquiries from concerned users. The purpose of the notice is to highlight ongoing connectivity issues due to firewalls, ISP blockages, etc. It’s not made for temporary connectivity issues. Th...

Beta Programs Fix, License Activation Enhancements, and more!

License Activation Enhancement

This release introduces several small, yet powerful, enhancements for the license activation screen. These annotations below go over each detail of the optimizations we’ve made, with details outlined below.

• The Hey {{ firstName }}, was removed to clean up some space.
• The welcoming message has changed from Thanks for purchasing {{ producTitle }} to Welcome to {{ producTitle }}, to be more... welcoming 🙂
• The updates & licensing mechanism disclaimer was adjusted to a more inclusive form.
• A tooltip was introduced next to "freemius.com" to explain the relation of the plugin/theme and Freemius.
• The permissions overview trigger was merged into the disclaimer and is now triggered by the "diagnostic data" link.
• The ADMIN NOTICES permission was removed since there's not much value in showing it for paid products.
• We realize that some people are very emotional about the plugins & themes permission even though it can be easily switched off. While there is a lot of value in collecting it, since it's not mission-critical and probably the most dreaded capability among our data practices, the option is now turned off by default when activating a license key.
• To reduce concerns even further, we added tooltips to all of the permissions to explain why they're needed.
• We've recently documented known license activation issues (with solutions) in our knowledge base, so, to save customers time and reduce your support load, we added a new License issues? link to this document right after the license activation button. If you prefer to copy the documentation to your knowledge base and link to that instead, you can use the known_license_issues_url filter.

This GIF showcases the updated license activation screen behavior:

Beta Programs

Just before we entered 2021, we discovered an issue in our implementation of the Beta Program functionality, and, therefore, temporarily paused delivery of beta releases. We've fixed the implementation, and this SDK version is now integrated with the fixed mechanism.

How to migrate beta users to the new mechanism?

First of all - you'll need to update the SDK to this latest version.
Then follow these instructions:

• Sign in to the Developer Dashboard and navigate to the USERS section of the relevant product.
• Change the filter to only show Beta Participants:
  
• Click DOWNLOAD USERS to get a CSV of all users who previously enrolled in your Beta Program:
  
• Finally, you'll need to send a message asking them to join the beta program again from the site(s) in which they want to receive updates with beta releases. Here's a copy you can use for your message:

Hi {{ firstName }},

Thanks again for being part of our Beta program and helping us test/improve/shape {{ producTitle }}.

Apologies for the hassle, but due to an issue that was discovered in our Beta releases mechanism, if you'd want to keep getting updates with Beta release, you'll need to enroll in the Beta program again.

If you are no longer interested in being part of the Beta Program, simply ignore this message.

Pricing Page

The SDK comes with a special mechanism to automatically use the newest version of the SDK available, whether it's included in your plugin/theme or in other Freemius-powered plugins/themes installed on a site.

We recently discovered that even if you haven't integrated our ReactJS-based pricing page, and another plugin/theme on the same website did, it was unexpectedly showing the new pricing for your product too.

Until we fully migrate to the new pricing page, we’ve updated it to only show up for products that include the build files in their product's code, even if there's another product running a newer version of the SDK.

Add-Ons Opt-In Behavior

To maximize the opt-in rate to usage-tracking, previously, activating an add-on would trigger the parent product's opt-in screen, even if the user had already skipped it before. After receiving some feedback, we realized this approach can be annoying, especially for products that usually need multiple add-ons installed just to get started.

We adjusted this behavior and from now on free add-ons inherit the opt-in state of their parent product.

Official release notes: https://freemius.com/blog/wordpress-sdk-242-license-activation-enhancement-beta-program-fix/