Integration & Configuration
Integrating the Freemius SDK into your product is a quick step you need to complete in order to be able to take advantage of all the benefits that come with using Freemius. After completing these instructions your product will be all set up and ready to sell.
Here’s how to do it:
After logging in to your Freemius account and clicking on the 'Add product / bundle' button at the top left hand corner you will be able to provide some basic settings for your product, including Slug and Title:
Upon hitting the ‘Create New’ button, you are then redirected to the 5-minute integration guide.
The next step is to download the ZIP file that contains the Freemius SDK and all of the Freemius magic that comes with it. You can download the latest release from our GitHub repository, unzip it, rename it to ‘freemius’.
Move the renamed freemius folder as-is in to the root folder of your WordPress theme or plugin.
With the Freemius SDK folder included in your product, you can complete the quick customization process according to the instructions on the SDK Integration page of the Developer Dashboard.
When you’re done, your customized ‘easy SDK access’ function will be auto-generated for you.
Note: This snippet of code initializes the Freemius SDK using an array of key/value pairs that contains specific information about your Freemius product and unlocks the full range of features available. Access to the Freemius SDK features comes via a global variable defined as part of the snippet.
For WordPress plugins, copy & paste it into the top of your main plugin’s PHP file, right after the plugin’s header comment and if ( ! defined( 'ABSPATH' ) ) exit; check.
For WordPress themes, copy & paste it into the top of your theme’s functions.php file.
Here’s how the code should look:
Under normal circumstances, we don't recommend editing the snippet directly once it's added to your WordPress product. However, there are times when you may need to tweak it manually. We'll cover when you might want to do this in a later section.
However, in all cases, you should begin by copying the snippet from the SDK Integration page of the Developer Dashboard and pasting it into your plugin or theme. Don't be tempted to try and create the snippet from scratch as this method is prone to errors. It's always best to start with the auto-generated snippet and tweak it when necessary.
Where to Add the SDK Integration Snippet
Depending on the structure of your plugin you may wish to add the SDK snippet to another location than your main plugin file. For themes, the SDK relies on the snippet to be placed in functions.php, if you place it elsewhere you are risking unexpected behavior - so please don’t do it.
Regardless of where it’s added, it's recommended that initialization of the Freemius SDK should be completed as soon as possible and preferably before any other code is executed inside your WordPress product.
This will help to minimize issues with trying to access SDK features before they are initialized. Also, SDK initialization should not occur after the WordPress 'plugins_loaded' hook. This is incorrect and will break some of the SDK's logic due to the execution order of other logic contained in WordPress core.
If you experience problems when placing the SDK snippet in a file alternative location than the recommended ones, then try adding it back in the main plugin file, to rule out any implementation errors.
Snippet Settings Reference
The array that's passed to fs_dynamic_init() consists of key-value pairs, including nested arrays for some settings. All possible values are covered as a reference guide, but not all will necessarily be relevant to your particular plugin or theme.
Specific settings will be generated depending on the information entered in the Developer Dashboard. Don't worry if your SDK snippet doesn't include all of the settings. This is perfectly normal.
All settings are listed below along with a description.
Note: All settings apply to both plugins and themes unless otherwise stated.
Auto-generated Freemius product ID which uniquely identifies your plugin or theme. This is created when the product is first created and cannot be changed.
Used to create the product folder name during deployment and in the updates mechanism. Also used in dynamically generated URLs (e.g. EULA).
Public key is a unique key prefixed with 'pk_' specific to the Freemium product. This is typically used for authentication with public Freemius API endpoints.
This setting is included if the affiliate program for the product is enabled (via the Developer Dashboard Affiliation page).
Its value is determined by the "Who can be an affiliate?" setting. When customers is selected, it means the seller only allows customers to become affiliates so the admin notice and menu item will only show up for customers. From the SDK's point of view, users and selected are identical, since only users will be exposed to the settings of the product in the WordPress admin.
An associative array containing configuration for opt-in moderation of your product. More on this later.
Secret key is a unique key prefixed with 'sk_' specific to the Freemium product. When present it enables sandbox mode for development & testing. It also elevates additional permissions that are helpful for development and testing modes.
Note: The secret key is automatically included in the SDK snippet for convenience. As per the comments in the snippet, this should be removed from production code, but don't worry if you forget as the PHP processor removes it automatically in the Deployment mechanism
Configuration for 'menu' array
Possible settings for the 'menu' array are:
The parent menu slug to use if the plugin settings page is a submenu of another menu. Even though this setting expects an array the slug field is the only option currently available.
This is where the plugin, or theme, will redirect to after activation.
Display the Freemius Contact Us page in the WordPress admin menu for the plugin or theme.
Display the Freemius Support Forum page in the WordPress admin menu for the plugin or theme.
Display the Freemius Add Ons page in the WordPress admin menu for the plugin or theme.
Display the Freemius Affiliation page in the WordPress admin menu for the plugin or theme.
If you set this to false then the SDK will not include any links to the Account page. If you are selling with Freemius the Account page is essential, therefore, make sure to manually link to that page from your settings interface using my_fs()->get_account_url().
Configuration for 'opt_in_moderation' array
The moderation configuration allows you to control how the Freemius WordPress SDK is activated for your customers. This is particularly useful when integrating the SDK into an existing product with active users, and you prefer not to display the Opt-In screen to all users at once. In such cases, we recommend performing a phased rollout of the integration to identify and resolve any issues before deploying it widely to your user base. Ideally,
- You control what percentages of new installations will see the Opt-In screen.
- You can also control what percentage of updated installations will see it.
This can be configured with the following parameters:
'opt_in_moderation' => array(
'new' => 100,
'updates' => 0,
'localhost' => true,
),
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.
This is the same as the 'new' parameter, 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).
Note: This setting was introduced in version 2.5.4 of the SDK. With the removal of the connectivity test, the moderation capabilities have been transitioned to the SDK settings. You can read more about it in our new release note.
Manually Editing the SDK Integration Snippet
There are certain fields that aren't updated or included by default in the auto-generated SDK snippet. Therefore, if you need to support a certain feature exposed by this type of field it will need to be added manually. This is best done after the snippet has been inserted into your WordPress product.
It's not usually recommended to edit any fields directly from the auto-generated snippet. Instead, the snippet should be updated by changing the settings for your plugin or theme in the Developer Dashboard.
Here's a list of the fields that can be manually inserted/edited:
Turn off all upgrade/pricing links except the account page. To enable this option it needs to be added to the 'menu' array which is automatically added to the snippet. If, for some reason, this doesn't exist, then you can add it manually and create a single entry for 'pricing' as follows: 'menu' => array( 'pricing' => false,),.
Bundle key is a unique key, and is specific to the Freemium bundle.
When set to true, an activation of a bundle license key will automatically activate the license key for all the other bundle's paid products installed on the site that are not yet associated with a license key.
The two bundle settings are required for products that are also sold as part of a bundle, when you want to sell the bundle via the WordPress admin instead of just the paid version of that product.
Example: For a freemium plugin with 10 paid add-ons, and you wish to sell a bundle of the plugin's paid version and 5 of the paid add-ons.
Without setting the bundle params in the SDK snippet, the in-dashboard pricing and checkout will be for the paid version of the plugin. On the other hand, when the params are set, the pricing page will show the prices of the bundle in context and that's what the user will purchase if they go through the checkout.
This is a key/value array where the key is a string (the permission name), and the value a boolean variable - which determines whether that permission is requested or not. Currently the only supported key is 'newsletter' and will explicitly ask a permission for "Updates, announcements, marketing, no spam".
Additional permissions may be available in the future to make it easy for you to pick and choose what permission their product needs on opt-in for. It's also possible for you to introduce yourr own custom permissions via the permission_list Freemius filter.
If your plugin is a Serviceware and cannot be used before creating an account, you can set this option to true and it will require users to opt-in after activation by removing the option to skip the opt-in.
When set to true it will automatically simulate a skip of an opt-in. This flag can be useful if you don’t want to ask users to opt-in to your free version or want to create your own custom opt-in interface, yet still utilize the power of the Freemius WordPress SDK (e.g. deactivation feedback form, in-dashboard checkout, etc.).
We highly recommend to use the SDK’s high-performing and multi-site network ready default opt-in, except if your product comes with an onboarding wizard and you’d want to custom add the opt-in UI and decision as part of that wizard.
To reset the “anonymous mode”, you can programmatically call my_fs()->connect_again(), which will also automatically redirect to the opt-in screen after resetting the flag. You can programmatically trigger a skip using my_fs()->skip_connection() or an opt-in consent using my_fs()->opt_in().
Use this to support parallel activation of both the free and premium versions of a WordPress plugin. Read more about it below
Parallel activation of Free and Premium versions
By default, our SDK automatically deactivates the free version of a plugin when the premium version is activated. However, you can modify this behavior using the following configuration:
'parallel_activation' => array(
'enabled' => true,
'premium_version_basename' => 'premium-slug/file-name.php',
),
With this configuration, the free version will remain active when the premium version is activated. Additionally, the SDK will display the license activation page if the free version has not yet been activated with a license.
Benefits of Parallel Activation
Parallel activation allows the “Active installs” counter on WordPress.org to include sites using the paid version without deactivating the free version. This is only useful if you distribute the free version on WordPress.org. If you don’t, this feature won’t provide you any benefits.
Drawbacks of Parallel Activation
This setup can create the perception that users need to manage updates for both the free and paid versions, leading to confusion about which version should be updated first. Additionally, there’s a risk of breaking functionality if major, non-backward compatible changes are made to one version. For this reason, we generally discourage parallel activation from a user experience (UX) perspective. Furthermore, since the typical conversion rate from free to paid is around 2%, the impact on the active installs counter is minimal.
While some of these manual settings may eventually be supported in the auto-generated snippet, for now, they must be added manually if needed.
Updating the SDK Integration Snippet
Whenever you make changes to your plugin or theme settings in the Developer Dashboard, this may trigger an update to the auto-generated SDK Integration snippet. It's important that whenever this is updated that you manually copy/paste it into your plugin or theme so that your product is always up to date with the latest version.
If the SDK integration snippet (minus any manual changes) doesn't match the Developer Dashboard version, then you could run into problems, so it's best to always keep it up-to-date and in sync when changes are made in the Developer Dashboard that affect the snippet.
The main reason why we don't recommend manually editing the SDK integration snippet (unless you have to) is because every time the snippet is updated inside your plugin or theme, you'll have to re-apply any manual changes you made previously. This can be tedious and prone to errors.
One final thing to remember is that if you have your SDK integration snippet in an alternative location (i.e. other than the main plugin file) then you'll also need to update the path reference to the Freemius SDK start.php file every time the snippet is updated.
Activate Opt-ins
Once you've completed the SDK integration, you can go back to the WordPress admin and activate & opt-in to your product (plugin or theme). If everything was done correctly, you should be able to see the data flowing into your Freemius dashboard in real time.
