# 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. ![SDK Integration Snippet - Freemius Developer Dashboard](/help/assets/ideal-img/sdk-integration.6da487f.480.png) 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. Fresh integration If you are just starting the integration process, we recommend you to beginning with the [Integration with SDK](https://freemius.com/help/help/documentation/wordpress/integration-with-sdk/.md) guide, which provides a step-by-step walkthrough of the entire integration process. ## The Integration Snippet Structure[​](#the-integration-snippet-structure "Direct link to 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](#snippet-settings-reference) section below. warning 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[​](#where-to-add-the-sdk-integration-snippet "Direct link to 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.php` file. 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. note 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[​](#snippet-settings-reference "Direct link to 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](#manual-configuration-options). 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. note * 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](https://freemius.com/help/help/documentation/wordpress/integration-with-sdk/.md#fill-out-the-sdk-integration-form). * The `my_fs` prefix as seen in [the example snippet](#the-integration-snippet-structure) 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 be `my_awesome_plugin_fs()`. This is the function you will use to access the Freemius SDK features in your plugin or theme code. ### Setting Options[​](#setting-options "Direct link to Setting Options") All the options are listed below with a description of their purpose and how to configure them: `id`[](#id "Direct link to id") number Example: 1234 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. `slug`[](#slug "Direct link to slug") string Example: 'my-plugin' Used to create the product folder name during deployment and in the updates mechanism. Also used in dynamically generated URLs (e.g. EULA). `premium_slug`[](#premium_slug "Direct link to premium_slug") string Example: 'my-plugin-pro' Used for freemium products to create the premium product’s version folder name during deployment. This needs to be different from the free version slug. Also used in dynamically generated URLs (e.g. EULA). `type`[](#type "Direct link to type") string Default: `'plugin'` Allowed Values: `'plugin'` | `'theme'` The type of WordPress product. `public_key`[](#public_key "Direct link to public_key") string Example: 'pk\_n56hrjss36joj632vgyy345ggv555' A unique key prefixed with 'pk\_' specific to the Freemium product and is typically used for authentication with public Freemius API endpoints. `is_premium`[](#is_premium "Direct link to is_premium") boolean Specify if the product’s codebase is the free or premium version. `premium_suffix`[](#premium_suffix "Direct link to premium_suffix") string Example: 'Pro' Default: `'plugin'` The suffix added to a premium plugin’s paid version title. This option is relevant for freemium products. `is_premium_only`[](#is_premium_only "Direct link to is_premium_only") boolean Default: `false` Specify if the plugin or theme is premium-only (i.e. no free version). This setting is added automatically at deployment if the default free plan is deleted and there's at least one paid plan. `has_premium_version`[](#has_premium_version "Direct link to has_premium_version") boolean Default: `false` Does the plugin or theme have a premium version available? `has_addons`[](#has_addons "Direct link to has_addons") boolean Default: `false` Does the plugin or theme have any associated addons? `has_paid_plans`[](#has_paid_plans "Direct link to has_paid_plans") boolean Default: `false` Does the plugin or theme have any paid plans? `is_org_compliant`[](#is_org_compliant "Direct link to is_org_compliant") boolean Default: `true` Is the product’s free version WordPress.org compliant. `has_affiliation`[](#has_affiliation "Direct link to has_affiliation") boolean|string Default: `false` Allowed Values: `'selected'` | `'customers'` | `'users'` This setting is included if the product's affiliate program is enabled via the Developer Dashboard [Affiliation page](https://freemius.com/help/help/documentation/affiliate-platform/affiliate-program-activation/.md). Its value is determined by the "Who can be an affiliate?" setting. `menu`[](#menu "Direct link to menu") array An array that denotes which Freemius pages to display in the WordPress admin menu, and how the plugin settings page menu is handled. If this doesn't exist and you need to add some nested settings, then add it manually as `'menu' => array()`. See the [configuration option](#configuration-for-menu-array) for the menu array. `opt_in_moderation`[](#opt_in_moderation "Direct link to opt_in_moderation") array An associative array containing configuration for opt-in moderation of your product. See the [configuration option](#configuration-for-opt_in_moderation_array) for the opt-in moderation array. `secret_key`[](#secret_key "Direct link to secret_key") string Example: 'sk\_84gbhR634gb732vy796h4gTY43' Default: `'plugin'` A unique key prefixed with 'sk\_' specific to the Freemium product. When present it enables [sandbox mode for development & testing](https://freemius.com/help/help/documentation/wordpress-sdk/testing/.md). 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 and **should be removed from production code**. However, if you forget, the PHP processor removes it automatically in the Deployment mechanism. `wp_org_gatekeeper`[](#wp_org_gatekeeper "Direct link to wp_org_gatekeeper") string Example: OA7sk184gbhR634gb732vy796h4gTY432mcpeVHi#C2j9d09fOTvbC0HloPT7fFee5WdS3G 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](https://freemius.com/help/help/documentation/wordpress-sdk/integration/software-licensing/.md). See how this [key works](https://freemius.com/blog/changelog/new-safeguard-against-uploading-premium-code-to-the-wordpress-org-repository/). ### Configuration for `'menu'` array[​](#configuration-for-menu-array "Direct link to configuration-for-menu-array") Add a nested array with the key `'menu'` to the main array passed to `fs_dynamic_init()`. ![WordPress admin menu with Freemius SDK Menu items](/help/assets/ideal-img/freemius-wordpress-sdk-menu.8622d66.386.png) The possible configuration options for the [`'menu'`](#menu) array are: `slug`[](#slug "Direct link to slug") string Example: 'my-plugin-menu' The WordPress admin menu slug used for the plugin settings page. `parent`[](#parent "Direct link to parent") string Example: array('slug' => 'options-general.php') 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. `first-path`[](#first-path "Direct link to first-path") string Example: 'admin.php?page=my-plugin-menu' This is where the plugin, or theme, will redirect to after activation. `contact`[](#contact "Direct link to contact") boolean Default: `true` Whether to display the Freemius **Contact Us** page in the WordPress admin menu for the plugin or theme. `support`[](#support "Direct link to support") boolean Default: `true` Whether to display the Freemius **Support Forum** page in the WordPress admin menu for the plugin or theme. `addons`[](#addons "Direct link to addons") boolean Default: `true` Whether to display the Freemius **Add Ons** page in the WordPress admin menu for the plugin or theme. `affiliation`[](#affiliation "Direct link to affiliation") boolean Default: `false` Whether to display the Freemius **Affiliation** page in the WordPress admin menu for the plugin or theme. `pricing`[](#pricing "Direct link to pricing") boolean Default: `true` 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)`. `account`[](#account "Direct link to account") boolean Default: `true` 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[​](#configuration-for-opt_in_moderation-array "Direct link to 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](https://freemius.com/help/help/documentation/wordpress-sdk/features/opt-in-screen/.md) when configured with the following parameters: ``` 'opt_in_moderation' => array( 'new' => 100, 'updates' => 0, 'localhost' => true, ), ``` `new`[](#new "Direct link to new") int|boolean Default: `true (as 100%)` 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. `updates`[](#updates "Direct link to updates") int|boolean Default: `true (as 100%)` 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. `localhost`[](#localhost "Direct link to localhost") boolean Default: `true` Whether to show the opt-in on localhost sites. note Note: This setting was introduced in [version 2.5.4 of the SDK](https://github.com/Freemius/wordpress-sdk/releases/tag/2.5.4). 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](https://freemius.com/blog/release-notes-wordpress-sdk-connectivity-test-stopped). ### Manual Configuration Options[​](#manual-configuration-options "Direct link to 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: `navigation`[](#navigation "Direct link to navigation") string Allowed Values: `'menu'` | `'tabs'` Enable [tabbed layout](https://freemius.com/help/help/documentation/wordpress-sdk/customization/tabs-navigation/.md) support for Freemius pages rather than display them as menu items. This is a very useful option to clean up the plugin’s admin menu structure if you have multiple Freemius pages and want to group them under a single menu item. `has_premium_version`[](#has_premium_version "Direct link to has_premium_version") boolean If your product is a Serviceware (a SaaS wrapped into a plugin or theme), set this option to `false`. This is an example of an option that is initially set in the auto-generated snippet but can be updated manually. `bundle_id`[](#bundle_id "Direct link to bundle_id") number Example: 1234 An auto-generated Freemius ID which uniquely identifies a specific bundle. `bundle_public_key`[](#bundle_public_key "Direct link to bundle_public_key") string Example: 'pk\_hrjss36joj632vgyy345ggv555' A unique key specific to the Freemium bundle. `bundle_license_auto_activation`[](#bundle_license_auto_activation "Direct link to bundle_license_auto_activation") boolean Default: `false` 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. note 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. `permissions`[](#permissions "Direct link to permissions") array\ Default: `false` 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". note 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](https://freemius.com/help/help/documentation/wordpress-sdk/features/opt-in-screen/.md) via the `permission_list` Freemius filter. `enable_anonymous`[](#enable_anonymous "Direct link to enable_anonymous") boolean 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. `anonymous_mode`[](#anonymous_mode "Direct link to anonymous_mode") boolean 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()`. `parallel_activation`[](#parallel_activation "Direct link to parallel_activation") array 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). ## Parallel activation of Free and Premium versions[​](#parallel-activation-of-free-and-premium-versions "Direct link to Parallel activation of Free and Premium versions") By default, our SDK [automatically deactivates the free version when the premium version is activated](#free-to-premium-upgrade-auto-deactivation). 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[​](#benefits-of-parallel-activation "Direct link to 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[​](#drawbacks-of-parallel-activation "Direct link to 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. note 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[​](#free-to-premium-upgrade-auto-deactivation "Direct link to 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: ``` 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[​](#updating-the-sdk-integration-snippet "Direct link to Updating the SDK Integration Snippet") Whenever you make changes to your plugin or theme settings in the [SDK Integration Form](https://freemius.com/help/help/documentation/wordpress/integration-with-sdk/.md#fill-out-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.