Understanding the Integration Snippet
The SDK integration snippet is a block of code that is generated based on the information you provide in the SDK Integration form in the Freemius Developer Dashboard.
It is essential for the proper functioning of the Freemius SDK in your WordPress product.
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.
The SDK integration snippet must be added to your plugin or theme for the SDK to work correctly. If the snippet is missing or incorrectly implemented, it can lead to issues with licensing, updates, and other features provided by the SDK.
If you are just starting the integration process, we recommend you to beginning with the Integration with SDK guide, which provides a step-by-step walkthrough of the entire integration process.
The Integration Snippet Structure
Access to the Freemius SDK features comes via a global variable defined as part of the snippet.
The global consists of an array passed to fs_dynamic_init() with key-value pairs, including nested arrays for some settings.
Here is an example of what the snippet looks like with a few of the possible settings:
/**
* This is for exhibition purposes only.
* Do not copy/paste this code directly into your plugin or theme.
* Copy/paste the auto-generated snippet from the Developer Dashboard.
*/
if ( ! function_exists( 'my_fs' ) ) {
function my_fs() {
// Global variable that will hold the Freemius instance.
global $my_fs;
if ( ! isset( $my_fs ) ) {
$my_fs = fs_dynamic_init(
array(
'id' => 12345,
'slug' => 'my-plugin',
'type' => 'plugin',
'public_key' => 'pk_n56hrjss36joj632vgyy345ggv555',
'menu' => array(
'pricing' =>true,
'contact' => true,
'support' => true,
'addons' => true,
'account' => true,
),
'is_org_compliant' => true,
)
);
}
return $my_fs;
}
}
To get a better understanding of the purpose of each setting and how to configure them, check out the Settings Reference section below.
The array with its settings must be directly passed into the fs_dynamic_init() function call as shown in the example above. Do not pass the array as a variable since this action will break the functionality of the SDK.
Where to Add the SDK Integration Snippet
To avoid any potential issues, we recommend copying & pasting the SDK integration snippet:
- For WordPress plugins, to 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, to the top of your theme’s
functions.phpfile.
Depending on the structure of your plugin you may wish to add the SDK snippet to another location than your main plugin file. We strongly recommend against this. Placing the snippet elsewhere risks unexpected behavior due to issues with the execution order of the SDK initialization.
However, if you do choose to place it in a separate file, make sure that this file is included very early in the execution process of your plugin or theme, ideally before any other code is executed.
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.
The 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.
Snippet Settings Reference
This segment provides a comprehensive reference for all the settings that can be included in the SDK integration snippet.
We don't recommend directly editing the snippet once it's added to your WordPress product 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.
However, there are times when you may need to tweak it manually. If you need to do that, make sure to understand the purpose of each setting in the snippet and how it affects the behavior of the SDK. This will help you make informed decisions about which settings to modify and how to do so without breaking the functionality of the SDK.
- All setting options below apply to both plugins and themes unless otherwise stated.
- All possible values are covered in the reference guide, but not all will necessarily be relevant to your particular plugin or theme. Don't worry, this is fine.
- Specific settings will be generated depending on the information input in the Developer Dashboard.
- The
my_fsprefix as seen in the example snippet will be a unique to your product to avoid conflicts with other products. For example, if your plugin is called "My Awesome Plugin", then the prefix will likely bemy_awesome_plugin_fs(). This is the function you will use to access the Freemius SDK features in your plugin or theme code.
Setting Options
All the options are listed below with a description of their purpose and how to configure them:
The product ID which uniquely identifies your plugin or theme. This is an auto-generated Freemius ID that cannot be changed and is created when the product is first added to the platform.
Used to create the product folder name during deployment and in the updates mechanism. Also used in dynamically generated URLs (e.g. EULA).
A unique key prefixed with 'pk_' specific to the Freemium product and is typically used for authentication with public Freemius API endpoints.
This setting is included if the product's affiliate program is enabled via the Developer Dashboard Affiliation page. Its value is determined by the "Who can be an affiliate?" setting.
An associative array containing configuration for opt-in moderation of your product.
See the configuration option for the opt-in moderation array.
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.
The secret key is automatically included in the SDK snippet for convenience and should be removed from production code. However, if you forget, the PHP processor removes it automatically in the Deployment mechanism.
Safeguard to prevent accidental uploading of premium versions of a product to the WordPress.org plugin repository.
The deployment mechanism adds this key/value pair when you have premium code in the product. The generated free version should not include this key unless you have premium code in it. To fix this, review how you are adding the license handling methods to your codebase.
See how this key works.
Configuration for 'menu' array
Add a nested array with the key 'menu' to the main array passed to fs_dynamic_init().
The possible configuration options 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.
Whether to display the Freemius Contact Us page in the WordPress admin menu for the plugin or theme.
Whether to display the Freemius Support Forum page in the WordPress admin menu for the plugin or theme.
Whether to display the Freemius Add Ons page in the WordPress admin menu for the plugin or theme.
Whether to display the Freemius Affiliation page in the WordPress admin menu for the plugin or theme.
Turn off all upgrade/pricing links except the account page.
To enable this option, manually create a single entry for 'pricing' as follows: 'menu' => array( 'pricing' => false).
Whether to display the Freemius Account page in the WordPress admin menu for the plugin or theme.
If you are selling with Freemius, the Account page is essential. You can 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.
This enables you to control what percentages of new and updated installations that will see the Opt-In screen when configured with the following parameters:
'opt_in_moderation' => array(
'new' => 100,
'updates' => 0,
'localhost' => true,
),
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.'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 this release note.
Manual Configuration Options
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.
Here's a list of the fields that can be manually inserted/edited:
An auto-generated Freemius ID which uniquely identifies a specific bundle.
A unique key specific to the Freemium bundle.
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. Set to true for automatic activation of a bundle license key.
This is particularly useful for bundles that include multiple paid products, as it streamlines the activation process for users by eliminating the need to manually activate each product's license key after purchasing the bundle.
The two bundle settings are required for products that are also sold as part of a bundle, when you intend to sell the bundle through the WordPress admin rather than only the standalone paid version of the product.
Example: Consider a freemium plugin with 10 paid add-ons, where you want to offer a bundle that includes the plugin’s paid version together with 5 of those add-ons.
If the bundle parameters are not configured in the SDK snippet, the in-dashboard pricing and checkout will reflect only the paid version of the plugin. However, once the parameters are properly set, the pricing page will display the bundle pricing in context, and users who proceed to checkout will purchase the bundle instead of just the standalone paid version.
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 your 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 when the premium version is activated. However, you can modify this behavior using the following configuration in the SDK snippet directly passed into the array under fs_dynamic_init().
'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.
Free to Premium Upgrade Auto-deactivation
For plugins with a Freemium model, the SDK comes with a special mechanism to auto deactivate the free version when activating the premium.
This is to prevent any potential conflicts between the two versions and ensure a smooth upgrade process for users. This mechanism is triggered when the SDK detects that both the free and premium versions are active at the same time, and it will automatically deactivate the free version to avoid any issues.
In order for this process to work properly, you'd need to slightly adjust the code of the main file. It should look like that:
<?php
/**
* Plugin Name: My Awesome Plugin
* .....
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
if ( function_exists( 'my_fs' ) ) {
my_fs()->set_basename( true, __FILE__ );
} else {
/**
* DO NOT REMOVE THIS IF, IT IS ESSENTIAL FOR THE
* `function_exists` CALL ABOVE TO PROPERLY WORK.
*/
if ( ! function_exists( 'my_fs' ) ) {
// Add the Freemius integration snippet
}
// Add your plugin's main file logic
}
Updating the SDK Integration Snippet
Whenever you make changes to your plugin or theme settings in the SDK Integration Form via the developer dashboard, it may trigger an update to the auto-generated SDK Integration snippet.
A mismatch in the settings can cause issues, so it's important that whenever an update happens, you manually copy/paste the updated snippet into your plugin's main file or theme's function.php file so that your product is always up to date with the latest settings.
If you have your SDK integration snippet in an alternative location other the recommended file, then you'll also need to update the path reference to the Freemius SDK start.php file every time the snippet is updated.