← All changes | freemius/README.md +82 -46 1.2.3 → trunk View file →

		@@ -1,70 +1,100 @@
1	1	Freemius WordPress SDK
2	2	======================
3	3
4		-[Monetization](https://freemius.com/wordpress/), [analytics](https://freemius.com/wordpress/insights/), and marketing automation platform for plugin & theme developers. Freemius empower developers to create prosperous subscription based businesses.
	4	+Welcome to the official repository for the Freemius SDK! Adding the SDK to your WordPress plugin, theme, or add-ons, enables all the benefits that come with using the [Freemius platform](https://freemius.com) such as:
5	5
6		-You can see some of the WordPress.org plugins & themes that are utilizing the power of Freemius here:
	6	+* [Software Licensing](https://freemius.com/wordpress/software-licensing/)
	7	+* [Secure Checkout](https://freemius.com/wordpress/checkout/)
	8	+* [Subscriptions](https://freemius.com/wordpress/recurring-payments-subscriptions/)
	9	+* [Automatic Updates](https://freemius.com/wordpress/automatic-software-updates/)
	10	+* [Seamless EU VAT](https://freemius.com/wordpress/collecting-eu-vat-europe/)
	11	+* [Cart Abandonment Recovery](https://freemius.com/wordpress/cart-abandonment-recovery/)
	12	+* [Affiliate Platform](https://freemius.com/wordpress/affiliate-platform/)
	13	+* [Analytics & Usage Tracking](https://freemius.com/wordpress/insights/)
	14	+* [User Dashboard](https://freemius.com/wordpress/user-dashboard/)
7	15
8		-https://includewp.com/freemius/#focus
	16	+* [Monetization](https://freemius.com/wordpress/)
	17	+* [Analytics](https://freemius.com/wordpress/insights/)
	18	+* [More...](https://freemius.com/wordpress/features-comparison/)
9	19
10		-If you are a WordPress plugin or theme developer and you are interested to monetize with Freemius you can [sign-up here for free](https://dashboard.freemius.com/register/):
	20	+Freemius truly empowers developers to create prosperous subscription-based businesses.
11	21
	22	+If you're new to Freemius then we recommend taking a look at our [Getting Started](https://freemius.com/help/documentation/getting-started/) guide first.
	23	+
	24	+If you're a WordPress plugin or theme developer and are interested in monetizing with Freemius then you can [sign-up for a FREE account](https://dashboard.freemius.com/register/):
	25	+
12	26	https://dashboard.freemius.com/register/
13	27
14		-**Below you'll find the integration instructions for our WordPress SDK.**
	28	+Once you have your account setup and are familiar with how it all works you're ready to begin [integrating Freemius](https://freemius.com/help/documentation/wordpress-sdk/integrating-freemius-sdk/) into your WordPress product
15	29
	30	+You can see some of the existing WordPress.org plugins & themes that are already utilizing the power of Freemius here:
	31	+
	32	+* https://profiles.wordpress.org/freemius/#content-plugins
	33	+* https://includewp.com/freemius/#focus
	34	+
16	35	## Code Documentation
17	36
18	37	You can find the SDK's documentation here:
19	38	https://freemius.com/help/documentation/wordpress-sdk/
20	39
21		-## Initializing the SDK
	40	+## Integrating & Initializing the SDK
22	41
23		-Copy the code below and paste it into the top of your main plugin's PHP file, right after the plugin's header comment:
	42	+As part of the integration process, you'll need to [add the latest version](https://freemius.com/help/documentation/getting-started/#add_the_latest_wordpress_sdk_into_your_product) of the Freemius SDK into your WordPress project.
24	43
	44	+Then, when you've completed the [SDK integration form](https://freemius.com/help/documentation/getting-started/#fill_out_the_sdk_integration_form) a snippet of code is generated which you'll need to copy and paste into the top of your main plugin's PHP file, right after the plugin's header comment.
	45	+
	46	+Note: For themes, this will be in the root `functions.php` file instead.
	47	+
	48	+A typical SDK snippet will look similar to the following (your particular snippet may differ slightly depending on your integration):
	49	+
25	50	```php
26		-<?php
	51	+if ( ! function_exists( 'my_prefix_fs' ) ) {
27	52	// Create a helper function for easy SDK access.
28	53	function my_prefix_fs() {
29	54	global $my_prefix_fs;
	55	+
30	56	if ( ! isset( $my_prefix_fs ) ) {
31	57	// Include Freemius SDK.
32	58	require_once dirname(__FILE__) . '/freemius/start.php';
33		-
	59	+
34	60	$my_prefix_fs = fs_dynamic_init( array(
35		- 'id' => '1234',
36		- 'slug' => 'my-plugin-slug',
37		- 'menu_slug' => 'my_menu_slug', // You can also use __FILE__
38		- 'public_key' => 'pk_MY_PUBLIC_KEY',
39		- 'is_live' => true,
40		- 'is_premium' => true,
41		- 'has_addons' => false,
42		- 'has_paid_plans' => false,
	61	+ 'id' => '1234',
	62	+ 'slug' => 'my-new-plugin',
	63	+ 'premium_slug' => 'my-new-plugin-premium',
	64	+ 'type' => 'plugin',
	65	+ 'public_key' => 'pk_bAEfta69seKymZzmf2xtqq8QXHz9y',
	66	+ 'is_premium' => true,
	67	+ // If your plugin is a serviceware, set this option to false.
	68	+ 'has_premium_version' => true,
	69	+ 'has_paid_plans' => true,
	70	+ 'is_org_compliant' => true,
	71	+ 'menu' => array(
	72	+ 'slug' => 'my-new-plugin',
	73	+ 'parent' => array(
	74	+ 'slug' => 'options-general.php',
	75	+ ),
	76	+ ),
43	77	// Set the SDK to work in a sandbox mode (for development & testing).
44	78	// IMPORTANT: MAKE SURE TO REMOVE SECRET KEY BEFORE DEPLOYMENT.
45		- 'secret_key' => 'sk_MY_SECRET_KEY',
	79	+ 'secret_key' => 'sk_ubb4yN3mzqGR2x8#P7r5&@*xC$utE',
46	80	) );
47	81	}
48		-
	82	+
49	83	return $my_prefix_fs;
50	84	}
51		-
	85	+
52	86	// Init Freemius.
53	87	my_prefix_fs();
54		-?>
	88	+ // Signal that SDK was initiated.
	89	+ do_action( 'my_prefix_fs_loaded' );
	90	+}
	91	+
55	92	```
56	93
57		-- **1234** - Replace with your plugin's ID.
58		-- **pk_MY_PUBLIC_KEY** - Replace with your plugin's public key.
59		-- **sk_MY_SECRET_KEY** - Replace with your plugin's secret key.
60		-- **my-plugin-slug** - Replace with your plugin's WordPress.org slug.
61		-- **my_menu_slug** - Replace with your admin dashboard settings menu slug.
62		-
63		-
64	94	## Usage example
65	95
66		-You can call the SDK by using the shortcode function:
	96	+You can call any SDK methods by prefixing them with the shortcode function for your particular plugin/theme (specified when completing the SDK integration form in the Developer Dashboard):
67	97
68	98	```php
69	99	<?php my_prefix_fs()->get_upgrade_url(); ?>
70	100	```
		@@ -77,12 +107,14 @@
77	107	$my_prefix_fs->get_account_url();
78	108	?>
79	109	```
80	110
81		-## Adding license based logic examples
	111	+There are many other SDK methods available that you can use to enhance the functionality of your WordPress product. Some of the more common use-cases are covered in the [Freemius SDK Gists](https://freemius.com/help/documentation/wordpress-sdk/gists/) documentation.
82	112
83		-Add marketing content to encourage your users to upgrade for your paid version:
	113	+## Adding license-based logic examples
84	114
	115	+Add marketing content that encourages your users to upgrade to a paid version:
	116	+
85	117	```php
86	118	<?php
87	119	if ( my_prefix_fs()->is_not_paying() ) {
88	120	echo '<section><h1>' . esc_html__('Awesome Premium Features', 'my-plugin-slug') . '</h1>';
		@@ -106,9 +138,9 @@
106	138	}
107	139	?>
108	140	```
109	141
110		-To add a function which will only be available in your premium plugin version, simply add __premium_only as the suffix of the function name. Just make sure that all lines that call that method directly or by hooks, are also wrapped in premium only logic:
	142	+To add a function which will only be available in your premium plugin version, add `__premium_only` as the suffix of the function name. Ensure that all lines that call that method directly or by hooks, are also wrapped in premium only logic:
111	143
112	144	```php
113	145	<?php
114	146	class My_Plugin {
		@@ -199,12 +231,12 @@
199	231	?>
200	232	```
201	233
202	234	## Excluding files and folders from the free plugin version
203		-There are two ways to exclude files from your free version.
	235	+There are [two ways](https://freemius.com/help/documentation/wordpress-sdk/software-licensing/#excluding_files_and_folders_from_the_free_plugin_version) to exclude files from your free version.
204	236
205		-1. Add `__premium_only` just before the file extension. For example, functions__premium_only.php will be only included in the premium plugin version. This works for all type of files, not only PHP.
206		-2. Add `@fs_premium_only` a sepcial meta tag to the plugin's main PHP file header. Example:
	237	+1. Add `__premium_only` just before the file extension. For example, functions__premium_only.php will be included only in the premium plugin version. This works for all types of files, not only PHP.
	238	+2. Add `@fs_premium_only` a special meta tag to the plugin's main PHP file header. Example:
207	239	```php
208	240	<?php
209	241	/**
210	242	* Plugin Name: My Very Awesome Plugin
		@@ -226,28 +258,32 @@
226	258
227	259	// ... my code ...
228	260	?>
229	261	```
230		-The file `/lib/functions.php` and the directory `/premium-files/` will be removed from the free plugin version.
	262	+In the example plugin header above, the file `/lib/functions.php` and the directory `/premium-files/` will be removed from the free plugin version.
231	263
232		-# WordPress.org Compliance
	264	+## Hooks: Actions and Filters
	265	+Similar to WordPress’ filters and actions hooks, the Freemius WordPress SDK provides a [collection of filters and actions](https://freemius.com/help/documentation/wordpress-sdk/filters-actions-hooks/) that enable you to customize and extend its functionality in your WordPress plugins or themes.
	266	+
	267	+## WordPress.org Compliance
233	268	Based on [WordPress.org Guidelines](https://wordpress.org/plugins/about/guidelines/) you are not allowed to submit a plugin that has premium code in it:
234	269	> All code hosted by WordPress.org servers must be free and fully-functional. If you want to sell advanced features for a plugin (such as a "pro" version), then you must sell and serve that code from your own site, we will not host it on our servers.
235	270
236		-Therefore, if you want to deploy your free plugin's version to WordPress.org, make sure you wrap all your premium code with `if ( my_prefix_fs()->{{ method }}__premium_only() )` or the other methods provided to exclude premium features & files from the free version.
	271	+Therefore, if you want to deploy your free plugin's version to WordPress.org, make sure you wrap all your premium code with `if ( my_prefix_fs()->{{ method }}__premium_only() )` or use [some of the other methods](https://freemius.com/help/documentation/wordpress-sdk/software-licensing/) provided by the SDK to exclude premium features & files from the free version.
237	272
238	273	## Deployment
239		-Zip your plugin's root folder and upload it in the Deployment section in the *Freemius Developer's Dashboard*.
240		-The plugin will be scanned and processed by a custom developed *PHP Processor* which will auto-generate two versions of your plugin:
	274	+Zip your Freemius product’s root folder and [upload it in the Deployment section](https://freemius.com/help/documentation/selling-with-freemius/deployment/) in the *Freemius Developer's Dashboard*.
	275	+The plugin/theme will automatically be scanned and processed by a custom-developed *PHP Processor* which will auto-generate two versions of your plugin:
241	276
242	277	1. **Premium version**: Identical to your uploaded version, including all code (except your `secret_key`). Will be enabled for download ONLY for your paying or in trial customers.
243	278	2. **Free version**: The code stripped from all your paid features (based on the logic added wrapped in `{ method }__premium_only()`).
244	279
245		-The free version is the one that you should give your users to download. Therefore, download the free generated version and upload to your site. Or, if your plugin was WordPress.org complaint and you made sure to exclude all your premium code with the different provided techniques, you can deploy the downloaded free version to the .org repo.
	280	+The free version is the one that you should give your users to download. Therefore, download the free generated version and upload to your site. Or, if your plugin was WordPress.org compliant and you made sure to exclude all your premium code with the different provided techniques, you can deploy the downloaded free version to the .org repo.
246	281
247		-## Reporting Bugs
248		-Email dev [at] freemius [dot] com
	282	+## License
	283	+Copyright (c) Freemius®, Inc.
249	284
250		-## FAQ
	285	+Licensed under the GNU general public license (version 3).
251	286
252		-## Copyright
253		-Freemius, Inc.
	287	+## Contributing
	288	+
	289	+Please see our [contributing guide](CONTRIBUTING.md).