Skip to content

Commit d5258ce

Browse files
ajaydsouzaajaydsouza
committed
Updated Readme
1 parent b499942 commit d5258ce

2 files changed

Lines changed: 166 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 149 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,149 @@
1-
# freemkit
2-
FreemKit
1+
# FreemKit
2+
3+
[![License](https://img.shields.io/badge/license-GPL_v2%2B-orange.svg?style=flat-square)](https://opensource.org/licenses/GPL-2.0)
4+
5+
__Requires at least:__ 6.6
6+
7+
__Tested up to:__ 6.9
8+
9+
__Requires PHP:__ 7.4
10+
11+
__License:__ [GPL-2.0+](http://www.gnu.org/licenses/gpl-2.0.html)
12+
13+
__Plugin page:__ [FreemKit](https://webberzone.com/plugins/freemkit/)
14+
15+
Seamlessly connect your Freemius with Kit email marketing to automate customer communications and marketing workflows.
16+
17+
## Description
18+
19+
WebberZone's FreemKit bridges the gap between Freemius and Kit (formerly ConvertKit) email marketing platforms, enabling WordPress plugin and theme developers to automate subscription workflows and enhance customer communication.
20+
21+
FreemKit receives Freemius webhook events in real time and subscribes customers to Kit forms and tags based on their subscription status. Webhooks are signature-verified using HMAC-SHA256, queued as WP transients, and processed asynchronously via WP-Cron — with deduplication and exponential-backoff retry built in. Subscriber records are persisted locally in a custom database table.
22+
23+
## Key features
24+
25+
- __Real-time Webhook Integration__ — Automatically sync customer data between Freemius and Kit through secure, signature-verified webhooks
26+
- __Automated List Management__ — Add or remove customers from Kit forms/tags based on their Freemius subscription status
27+
- __Custom Field Mapping__ — Map Freemius customer data to Kit custom fields for personalised email marketing
28+
- __Per-plugin Configuration__ — Configure separate free/paid form IDs, tag IDs, and event types for each of your Freemius products
29+
- __Secure Implementation__ — HMAC-SHA256 signature verification, nonce checks, capability checks, and sanitised input throughout
30+
- __Flexible Webhook Endpoint__ — Choose between a REST API endpoint or a query variable fallback
31+
- __Async Processing__ — Webhooks are queued and processed via WP-Cron with deduplication and retry logic
32+
- __Local Subscriber Records__ — Subscriber data is stored in a custom database table for reference and auditing
33+
- __Setup Wizard__ — Get started quickly with a guided setup wizard on first activation
34+
- __Developer-Friendly__ — Extensible through WordPress filters and actions
35+
36+
## Installation
37+
38+
### Manual install
39+
40+
1. Download the latest release from the [releases page](https://github.com/WebberZone/freemkit/releases)
41+
2. Upload the `freemkit` folder to `/wp-content/plugins/`
42+
3. Activate the plugin through the __Plugins__ menu in WordPress
43+
4. Navigate to __Settings → FreemKit__ and connect your Kit account via OAuth
44+
5. Enter your __Freemius Secret Key__ and register the webhook URL in Freemius
45+
46+
## Setting Up the Freemius Webhook
47+
48+
FreemKit receives events from Freemius in real time via webhooks. You must register the webhook URL in your Freemius Developer Dashboard for the integration to work.
49+
50+
### Step 1 — Find your Webhook URL
51+
52+
Go to __Settings → FreemKit → Webhook__ in your WordPress admin. The plugin shows the correct URL based on your chosen endpoint type:
53+
54+
| Endpoint type | URL format |
55+
|---|---|
56+
| REST API *(recommended)* | `https://yourdomain.com/wp-json/freemkit/v1/webhook` |
57+
| Query variable | `https://yourdomain.com/?freemkit_webhook=1` |
58+
59+
You can switch between the two under __Webhook Endpoint Type__ on the same settings page.
60+
61+
### Step 2 — Register the webhook in Freemius
62+
63+
1. Log in to the [Freemius Developer Dashboard](https://dashboard.freemius.com) and open your product
64+
2. Go to __Integrations → Webhooks → Listeners__ and click __Add Webhook__
65+
3. Paste the Webhook URL from Step 1
66+
4. Choose the events to subscribe to. Recommended minimum:
67+
- `install.installed` — fires when a user installs your product (maps to free users)
68+
- `license.created` — fires when a paid license is created (maps to paid users)
69+
5. Save the webhook. You can activate it immediately or defer activation.
70+
71+
### Step 3 — Add your Freemius Secret Key
72+
73+
Freemius signs every webhook request with your product's __Secret Key__ using HMAC-SHA256. FreemKit verifies this signature and will reject any request that doesn't match.
74+
75+
1. In the Freemius Developer Dashboard, go to your product's __Settings → General__ and copy the __Secret Key__
76+
2. Paste it into __Settings → FreemKit → Freemius Secret Key__ and save
77+
78+
## Configuration
79+
80+
After activation, the setup wizard guides you through the initial configuration. You can also configure the plugin at __Settings → FreemKit__:
81+
82+
1. __Connect Kit__ — Authenticate via OAuth to link your Kit account
83+
2. __Set Global Defaults__ — Configure default Kit form/tag IDs for free and paid users
84+
3. __Per-plugin Overrides__ — Set separate form IDs, tag IDs, and event types per Freemius product
85+
4. __Custom Field Mapping__ — Map Freemius customer data fields to Kit custom fields
86+
5. __Webhook Settings__ — Choose your endpoint type and review the webhook URL to register in Freemius
87+
88+
## Development
89+
90+
```bash
91+
# Lint PHP (WordPress coding standards)
92+
composer phpcs
93+
94+
# Auto-fix PHP code style
95+
composer phpcbf
96+
97+
# Static analysis
98+
composer phpstan
99+
100+
# Run all checks
101+
composer test
102+
103+
# Build JS/CSS assets
104+
npm run build
105+
106+
# Watch mode
107+
npm start
108+
```
109+
110+
## Other plugins by WebberZone
111+
112+
FreemKit is one of the many plugins developed by WebberZone. Check out our other plugins:
113+
114+
- [Contextual Related Posts](https://wordpress.org/plugins/contextual-related-posts/) - Display related posts on your WordPress blog and feed
115+
- [Top 10](https://wordpress.org/plugins/top-10/) - Track daily and total visits to your blog posts and display the popular and trending posts
116+
- [WebberZone Snippetz](https://wordpress.org/plugins/add-to-all/) - The ultimate snippet manager for WordPress to create and manage custom HTML, CSS or JS code snippets
117+
- [Knowledge Base](https://wordpress.org/plugins/knowledgebase/) - Create a knowledge base or FAQ section on your WordPress site
118+
- [Better Search](https://wordpress.org/plugins/better-search/) - Enhance the default WordPress search with contextual results sorted by relevance
119+
- [Auto-Close](https://wordpress.org/plugins/autoclose/) - Automatically close comments, pingbacks and trackbacks and manage revisions
120+
- [Popular Authors](https://wordpress.org/plugins/popular-authors/) - Display popular authors in your WordPress widget
121+
- [Followed Posts](https://wordpress.org/plugins/where-did-they-go-from-here/) - Show a list of related posts based on what your users have read
122+
123+
## Contribute
124+
125+
FreemKit is also available on [GitHub](https://github.com/WebberZone/freemkit).
126+
So, if you've got a cool feature you'd like to implement in the plugin or a bug you've fixed, consider forking the project and sending me a pull request.
127+
128+
Bug reports are [welcomed on GitHub](https://github.com/WebberZone/freemkit/issues). Please note that GitHub is *not* a support forum, and issues that aren't suitably qualified as bugs will be closed.
129+
130+
## Support
131+
132+
- __Documentation__: [webberzone.com/support/freemkit/](https://webberzone.com/support/freemkit/)
133+
- __GitHub Issues__: [github.com/WebberZone/freemkit/issues](https://github.com/WebberZone/freemkit/issues)
134+
135+
## Translations
136+
137+
FreemKit is available for [translation directly on WordPress.org](https://translate.wordpress.org/projects/wp-plugins/freemkit). Check out the official [Translator Handbook](https://make.wordpress.org/polyglots/handbook/plugin-theme-authors-guide/) to contribute.
138+
139+
## License
140+
141+
This plugin is licensed under the GPL-2.0+ license.
142+
143+
## Credits
144+
145+
FreemKit is developed and maintained by [WebberZone](https://webberzone.com/).
146+
147+
## About this repository
148+
149+
This GitHub repository always holds the latest development version of the plugin. Beta and stable releases are made available under [releases](https://github.com/WebberZone/freemkit/releases).

‎readme.txt‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@ Stable tag: 1.0.0
88
License: GPLv2 or later
99
License URI: https://www.gnu.org/licenses/gpl-2.0.html
1010

11-
Seamlessly connect your Freemius software licensing with Kit email marketing to automate customer communications and marketing workflows.
11+
Seamlessly connect your Freemius with Kit email marketing to automate customer communications and marketing workflows.
1212

1313
== Description ==
1414

15-
WebberZone's FreemKit bridges the gap between Freemius software licensing and Kit (formerly ConvertKit) email marketing platforms, enabling WordPress plugin and theme developers to automate subscription workflows and enhance customer communication.
15+
WebberZone's FreemKit bridges the gap between Freemius and Kit (formerly ConvertKit) email marketing platforms, enabling WordPress plugin and theme developers to automate subscription workflows and enhance customer communication.
1616

1717
= Key Features =
1818

@@ -45,8 +45,11 @@ WebberZone's FreemKit bridges the gap between Freemius software licensing and Ki
4545
1. Upload the `freemkit` folder to the `/wp-content/plugins/` directory.
4646
2. Activate the plugin through the 'Plugins' menu in WordPress.
4747
3. Navigate to Settings → FreemKit to configure your Freemius and Kit API credentials.
48-
4. Set up your desired automation rules and field mappings.
49-
5. Test the integration using the built-in testing tools.
48+
4. Copy the **Webhook URL** displayed on the settings page.
49+
5. In your [Freemius Developer Dashboard](https://dashboard.freemius.com), open your product, go to **Integrations → Webhooks → Listeners**, click **Add Webhook**, paste the URL, choose the events to subscribe to, and save.
50+
6. Enter your product's **Secret Key** (found in Freemius under Settings → General) into the FreemKit settings so signatures can be verified.
51+
7. Set up your desired automation rules and field mappings.
52+
8. Test the integration using the built-in testing tools.
5053

5154
== Frequently Asked Questions ==
5255

@@ -58,10 +61,20 @@ WebberZone's FreemKit bridges the gap between Freemius software licensing and Ki
5861
* Active Kit account with API access.
5962
* Valid API credentials for both services.
6063

64+
= How do I add the webhook in the Freemius Developer Dashboard? =
65+
66+
1. Log in to your [Freemius Developer Dashboard](https://dashboard.freemius.com) and open the product you want to connect.
67+
2. Navigate to **Integrations → Webhooks → Listeners** and click **Add Webhook**.
68+
3. Paste the **Webhook URL** shown on the FreemKit settings page. By default this is `https://yourdomain.com/wp-json/freemkit/v1/webhook` (REST API endpoint). If you use the query-variable endpoint it will be `https://yourdomain.com/?freemkit_webhook=1`.
69+
4. Choose which events to send — at minimum select `install.installed` (for free users) and `license.created` (for paid users), or select **All Events** if you want full coverage.
70+
5. Save the webhook. Freemius will sign every request with your product's **Secret Key** using HMAC-SHA256.
71+
6. Copy the **Secret Key** from your Freemius product settings (Settings → General) and enter it in the FreemKit settings page so the plugin can verify incoming requests.
72+
6173
= Is it secure? =
6274

6375
Yes! The plugin is built with security in mind:
6476
* All API communications are encrypted
77+
* Validates every incoming webhook request using HMAC-SHA256 signatures against your Freemius product secret key
6578
* Implements WordPress nonce verification
6679
* Includes proper user capability checks
6780
* Features comprehensive input sanitization

0 commit comments

Comments
 (0)