WPBay SDK Documentation

Below is a comprehensive documentation for the WPBay SDK, which is intended to help developers integrate the SDK into their WordPress plugins and themes. The SDK allows you to distribute and sell your products via WPBay.com (similar to the Freemius SDK).

Overview
Requirements and Installation
Basic Integration Steps
Understanding the SDK Parameters
Adding Settings/Registration Menus
Handling Updates & Activation
License Checks and Verification
Adding the Contact Form and Upgrade Form into your menus
Error Handling and Custom Logger
Frequently Asked Questions (FAQ)
Support & Further Resources

1. Overview

The WPBay SDK is a library that you include in your WordPress plugin or theme which are sold on WPBay.com, in order to:

Sell and manage your product licenses through WPBay.com.
Handle plugin/theme updates directly from WPBay.com (instead of using WordPress.org). Users who have a valid and activated license for the plugins or themes will be able to update them directly in WordPress, with the latest version of the product uploaded to WPBay.com
Handle premium/paid features via license checks.
Display product or license management options in the WordPress Admin.
Display custom admin pages for support, feedback, and more.
Gather optional usage statistics (if enabled).
Show rating or upgrade notices (for paid or premium versions of your plugins or themes).

This document will guide you through the steps to integrate the WPBay SDK into your WordPress product, from initial setup and configuration to advanced usage scenarios like developer mode, custom forms, and more.

Join the WPBay Community (Bonus)

We’re working on creating a helpful community of WPBay developers for tips, tutorials, and best practices. While it’s not as extensive as some other communities yet, keep an eye on your WPBay.com account dashboard for announcements about invite-only groups or forums. This is a great opportunity to:

Ask questions and get peer support from fellow WPBay developers.
Share marketing, pricing, and development insights.
Stay updated on new WPBay features and improvements.

As a first step to join our community, you can check WPBay’s Discord server.

The Quick Integration Guide

Ready to get started? Here’s a bird’s-eye view:

Download the WPBay SDK and place it in your plugin or theme folder.
Initialize the SDK in your main file with your api_key, which can be found in your WPBay Seller Dashboard.
Configure additional parameters like is_free, is_upgradable and more.
Activate your product locally or on a test site to confirm everything works, using the developer mode (details below). Don’t forget to deactivate the developer mode once you finished testing the SDK integration into your plugin or theme.
Go Live! Upload your product to WPBay and start selling!

2. Requirements and Installation

WordPress Version
The WPBay SDK works with WordPress 4.9+ (though we recommend the latest version).
PHP Version
The minimum PHP version required is 7.0 or higher.
Installing the SDK
Download the WPBay SDK from here. Extract the zip file and find the wpbay-sdk folder, which needs to be placed inside your plugin’s or theme’s root directory, for example:
```
my-plugin/
├── wpbay-sdk/
│   ├── WPBay_Loader.php
│   ├── ...
├── my-plugin.php
└── ...
```
Multiple Instances
The WPBay SDK sets a global variable to ensure only the latest version is loaded if multiple plugins or themes are using it (each having different versions of the SDK). It will automatically handle to load always the latest version which is found to be active.

3. Basic Integration Steps

Below is a step-by-step outline of how to integrate the WPBay SDK to your theme or plugin. We will reference parts of the sample code from your example.

3.1. Include the WPBay SDK in Your Plugin/Theme

In the main file of your plugin or theme (e.g., my-plugin.php of your plugin, or functions.php of your theme), add a function that requires the WPBay_Loader.php file. This file is responsible for loading and managing the WPBay SDK. You can generate this function dynamically, using the tool from below:

WPBay SDK Configuration Generator

Function Name For The SDK Loader (Unique)*:

Your API Key*:

WPBay Product ID (optional):

Activation Redirect (optional):

Options Is Free Is Upgradable Uploaded to WP.org Disable Support Page Disable Feedback (active only if you enter a valid WPBay product ID) Disable Contact Form (active only if you enter a valid WPBay product ID) Disable Upgrade Form (active only if you enter a valid WPBay product ID) Disable Analytics (active only if you enter a valid WPBay product ID) No Activation Required

Rating Notice:

Debug Mode:

Menu Configuration

Top-Level Menu Slug (if you have a menu for the theme/plugin):

Custom Post Type (if you use a custom post type as the menu of your theme/plugin):

Parent Page Menu (if your theme/plugin is inside a parent page):

SDK Loader PHP Code To Add To Your Theme Or Plugin:

3.2. Debug Mode (Optional)

If you set the ‘debug_mode’ SDK parameter to true, all errors will be logged in the wpbay_info.log file, found in the /wp-content folder. This feature can be helpful for debugging, don’t forget to set it to false in production.

3.3. Developer Mode (Optional)

If you want to debug or test the plugin without talking to WPBay’s live servers, you can enable Developer Mode. This is useful to test integration of the SDK into plugins or themes which are not yet uploaded or live on WPBay. Activate it using a modified version of the below code (example code for the “MY_TEST_PLUGIN” slug):


define( 'WPBAY_MY_TEST_PLUGIN_DEVELOPER_MODE', true );
define( 'WPBAY_MY_TEST_PLUGIN_SECRET_KEY', 'YOUR_SECRET_KEY' );

MY_TEST_PLUGIN in the constant name can be replaced with your plugin slug (the slug MUST be the directory name of your plugin/theme). This needs to be configured in your admin dashboard, in the “Allowed Testing Slugs” section. Be sure to add the same slug in your WPBay seller settings as you add in the code of the plugin. WPBay will check this slug and will accept developer activations only for slugs listed in your account settings. Once you are done with testing, you can remove the slug from settings to disable developer activations and testing.
YOUR_SECRET_KEY is provided by WPBay, check your account and copy your Developer Secret Key.

NOTE: You can also automatically generate your Developer Mode PHP activation code, if you enter a testing slug in your account dashboard. Be sure to enter the correct slug (directory name) of your plugin or theme, for this feature to work correctly!

When DEVELOPER_MODE is true, the SDK will not perform real license checks against WPBay’s production server. Replace YOUR_SECRET_KEY with your own secret key in the above code. You can get your ‘Developer Secret Key’ from your Seller Dashboard.

To activate the plugin or theme in testing mode (without a real purchase code, which results after a purchase of your product from WPBay), use your secret ‘Developer Testing Purchase Code‘ found in your admin dashboard and place it in your wp-config.php file, on the local server where you are testing integration.

The developer testing license, once activated, will be visible in your your admin dashboard, in the ‘Existing Sandbox Activations’ section. Any developer testing licenses will automatically expire after 24 hours. They can also be revoked manually, for testing purposes.

When in Developer Mode, you will have access to a series of additional testing tools for the SDK, found in WordPress admin menu -> Tools -> ‘WPBay Developer Mode’ settings menu entry. Give it a try to test license activation/deactivation events.

3.4. Configure SDK Parameters

Once you have included WPBay_Loader.php, you need to pass an array of SDK parameters (which can be configured easily using the provided tool from above):


$sdk_params = array(
    'api_key'                 => 'YOUR_API_KEY',
    'wpbay_product_id'        => 'YOUR_PRODUCT_ID',
    'product_file'            => __FILE__,
    'activation_redirect'     => 'options-general.php?page=wpbay-settings',
    'is_free'                 => false,
    'is_upgradable'           => false,
    'uploaded_to_wp_org'      => false,
    'disable_feedback'        => false,
    'disable_support_page'    => false,
    'disable_contact_form'    => false,
    'disable_upgrade_form'    => false,
    'disable_analytics'       => false,
    'debug_mode'              => false,
    'rating_notice'           => '1 week',
    'no_activation_required'  => false,
    'menu_data'               => array(
        'menu_slug' => 'my_plugin_admin_settings',
    ),
);

See Understanding the SDK Parameters for more details on each parameter.

3.5. Load the SDK

Finally, you need to call the load_sdk() method. The standard pattern is:


global $wpbay_sdk_latest_loader; // set by WPBay_Loader.php
$sdk_loader_class = $wpbay_sdk_latest_loader;

if ( class_exists( $sdk_loader_class ) ) {
    $sdk_instance = $sdk_loader_class::load_sdk( $sdk_params );
}

The load_sdk() method initializes the SDK with your product’s parameters and sets up license checks, updates, admin notices, etc.

4. Understanding the SDK Parameters

Here are the most important parameters you can pass in $sdk_params:

api_key (string) – Your WPBay API key.
wpbay_product_id (string or int) – The unique product ID from WPBay.
product_file (string) – Path to your main plugin file (usually __FILE__ – don’t change this).
activation_redirect (string) – Page slug to redirect to after activation (e.g., options-general.php?page=wpbay-settings – optional).
is_free (bool) – If true, the product is free, skipping certain license checks.
is_upgradable (bool) – If true, the user can upgrade from a free to paid plan.
uploaded_to_wp_org (bool) – Set this true if your plugin is hosted on the WordPress.org repo.
disable_feedback (bool) – Disables user feedback requests if set to true.
disable_support_page (bool) – Disables creation of a support/FAQ page if set to true.
disable_contact_form (bool) – Disables auto adding to your plugin menus of the built-in contact form if set to true.
disable_upgrade_form (bool) – Disables auto adding to your plugin menus of the built-in contact form if set to true.
disable_analytics (bool) – Disable usage analytics collection if set to true.
rating_notice (string) – When to display a rating notice (e.g., '1 week'); set empty or false to disable.
debug_mode (string) – To enable SDK debug mode, to create logs of failures.
no_activation_required (bool) – If true, the plugin runs without license activation (e.g., for free/trial mode).
menu_data (array) – Configuration for automatically creating admin menus. Example:


'menu_data' => array(
  'menu_slug'   => 'my_plugin_admin_settings',
  // 'parent' => array('menu_slug' => 'options-general.php'),
),

5. Adding Settings/Registration Menus

The WPBay SDK can create its own top-level or sub-level menus based on menu_data. However, you can also define your own menu if you need more control. For example:


add_action('admin_menu', 'my_plugin_register_admin_menu');
function my_plugin_register_admin_menu() {
    $slug = 'my_plugin_admin_settings';
    add_menu_page(
        'My Plugin Settings',
        'My Plugin',
        'manage_options',
        $slug,
        'my_plugin_admin_settings_callback'
    );
}

function my_plugin_admin_settings_callback() {
    echo '<h1>My Plugin Settings</h1>';
    // Your settings form or content.
}

If disable_support_page is false, the SDK can automatically create a “Support” page for you. You can specify a parent or top-level slug in menu_data.

6. Handling Updates & Activation

License Activation: If is_free and no_activation_required are both false, WPBay prompts for a license key. Otherwise, the plugin may activate automatically.
Automatic Updates: If a valid license is active (or not required), the SDK checks WPBay’s servers for updates. Updates appear in the normal WordPress “Plugins” update screen.
Deactivation: Deactivating the plugin optionally notifies WPBay servers to free the license seat for use on another domain.

7. License Checks and Verification

When DEVELOPER_MODE is enabled, all license verification checks are skipped locally, allowing developers to test functionality without requiring a valid license. Otherwise, the SDK will attempt to verify licenses using your api_key and wpbay_product_id. These credentials are used to authenticate and validate the user’s license status against the WPBay licensing system.

The WPBay_SDK class provides a set of methods to check and manage license states, user types, and product configurations. Below is a detailed breakdown of the available license verification and utility functions.

7.1 License Verification Methods

`is_paid_or_trial_user()`

Description: Checks if the user is either a paying customer or a trial user.
Return: boolean – Returns true if the user has a paid license or is on a trial, false otherwise.
Usage:


$sdk = new WPBay_SDK(); 
if ($sdk->is_paid_or_trial_user()) 
{ 
    echo "User has an active paid or trial license."; 
} 
else 
{ 
    echo "User does not have a valid license."; 
}

This method combines the results of is_paying_user() and is_trial_user() for convenience.

`is_not_paying_user()`

Description: Determines if the user is not a paying customer.
Return: boolean – Returns true if the user does not have a paid license, false if they do.
Usage:


if ($sdk->is_not_paying_user()) 
{ 
    echo "Please upgrade to a paid plan."; 
}

This method is the inverse of is_paying_user() and is useful for prompting users to upgrade.

`is_trial_user()`

Description: Checks if the user is on a trial plan.
Return: boolean – Returns true if the user has a valid trial license, false otherwise.
Usage:


if ($sdk->is_trial_user()) 
{ 
    echo "You are currently on a trial plan."; 
}

This method verifies that a purchase code exists and that the license plan is specifically marked as ‘trial’ via the license_manager.

`is_paying_user()`

Description: Checks if the user has an active paid license.
Return: boolean – Returns true if the user has a paid license, false otherwise.
Usage:


if ($sdk->is_paying_user()) 
{ 
    echo "Thank you for being a paid customer!"; 
}

This method confirms the presence of a purchase code and ensures the plan is not a trial.

`is_plan($plan_name)`

Description: Verifies if the user’s license matches a specific plan name. Currently the only plan available (set by default for products) is: ‘wpbay’. New updates for WPBay will bring support for product plans, which will use this feature.
Parameters:

$plan_name (string) – The name of the plan to check (e.g., ‘trial’, ‘premium’).

Return: boolean – Returns true if the user’s plan matches the specified $plan_name, false otherwise.
Usage:


if ($sdk->is_plan('premium')) 
{ 
    echo "You are on the Premium plan."; 
}

This method delegates to the license_manager to compare the current plan against the provided $plan_name.

7.2 Product Type Verification Methods

`is_theme()`

Description: Checks if the product is a theme.
Return: boolean – Returns true if the product type is ‘theme’, false otherwise.
Usage:


if ($sdk->is_theme()) 
{ 
    echo "This is a WPBay theme."; 
}

`is_plugin()`

Description: Checks if the product is a plugin.
Return: boolean – Returns true if the product type is ‘plugin’, false otherwise.
Usage:


if ($sdk->is_plugin()) 
{ 
    echo "This is a WPBay plugin."; 
}

7.3 Development and Debugging Modes

`is_developer_mode()`

Description: Checks if developer mode is enabled.
Return: boolean – Returns true if DEVELOPER_MODE is set to ‘1’, false otherwise.
Usage:


if ($sdk->is_developer_mode()) 
{ 
    echo "Developer mode is active; license checks are bypassed."; 
}

When developer mode is active, all license verification checks are skipped, making it ideal for local testing.

`is_debug_mode()`

Description: Checks if debug mode is enabled.
Return: boolean – Returns true if debug_mode is set to true, false otherwise.
Usage:


if ($sdk->is_debug_mode()) 
{ 
    echo "Debug mode is enabled."; 
}

Debug mode can be used to enable additional logging or diagnostic output during development.

7.4 Manager Access Methods

`get_contact_form_manager()`

Description: Retrieves the contact form manager instance.
Return: object – The contact_form_manager object.
Usage:


$contact_manager = $sdk->get_contact_form_manager(); 
$contact_manager->render_contact_form();

`get_upgrade_form_manager()`

Description: Retrieves the upgrade/purchase form manager instance.
Return: object – The purchase_manager object.
Usage:


$upgrade_manager = $sdk->get_upgrade_form_manager(); 
$upgrade_manager->render_upgrade_form();

7.5 Notes

All license-related methods rely on the license_manager object to fetch and validate purchase codes and plan details.
Ensure that api_key and wpbay_product_id are correctly configured in your SDK initialization to avoid verification failures.
When DEVELOPER_MODE is disabled, the SDK will perform online verification, which requires an active internet connection.

8. Adding the Contact Form and Upgrade Form into your menus

The SDK will automatically create a Contact and Upgrade menu in your plugin, if you enable these features and also set ‘disable_upgrade_form’ and ‘disable_contact_form’ to false. If you don’t want to get these menus added automatically, but you want to add this functionality to your custom plugin menus, you can set the above flags to true and add the contact form and upgrade form into your plugin, using the below code (example):


    //REPLACE THIS WITH THE CUSTOM FUNCTION NAME WHICH LOADS THE WPBAY SDK IN YOUR CODE
    $sdk_instance = testing_wpbay_sdk();

    //ADD THE UGRPADE FORM
    $upgrade_manager = $sdk_instance->get_upgrade_form_manager();
    if ($upgrade_manager) {
        echo '<div class="wrap"><h1>' . esc_html__('Upgrade', 'wpbay-sdk') . '</h1>';
        $upgrade_manager->render_upgrade_form();
        echo '</div>';
    } else {
        echo '<div class="wrap"><h1>' . esc_html__('Upgrade', 'wpbay-sdk') . '</h1>';
        echo '<p>' . esc_html__('Upgrade form is disabled or not available.', 'wpbay-sdk') . '</p>';
        echo '</div>';
    }


    //ADD THE CONTACT FORM
    $contact_manager = $sdk_instance->get_contact_form_manager();
    if ($contact_manager) {
        echo '<div class="wrap"><h1>' . esc_html__('Contact', 'wpbay-sdk') . '</h1>';
        $contact_manager->render_contact_form();
        echo '</div>';
    } else {
        echo '<div class="wrap"><h1>' . esc_html__('Contact', 'wpbay-sdk') . '</h1>';
        echo '<p>' . esc_html__('Contact form is disabled or not available.', 'wpbay-sdk') . '</p>';
        echo '</div>';
    }

9. Frequently Asked Questions (FAQ)

Do I need a separate SDK for each product?
Yes. You need to add the SDK into each of your products, as they will be able to be installed also separately, each on a different webiste, so they cannot share a single copy of the SDK. However, you can share the api_key between multiple products you create and manage.
Where do I get my api_key and wpbay_product_id?
To get your API key, log into WPBay.com and check your API in your Dashboard. To get the product_id for your plugins/themes, upload them to WPBay and you will get a numeric product ID for each of them after they are approved.
Can I offer premium add-ons?
Yes. You can have a base plugin (is_free => true) and add-ons that integrate the WPBay SDK with their own IDs.
Is WPBay SDK GPL-compliant?
Yes, it’s under a GPL-compatible license.
I have more questions, how can I get in touch?
Join our Discord server or send us an email to support [at] wpbay.com

Example Integration in Full

Here is a complete example (close to your provided snippet) with explanatory comments:


<?php
/*
Plugin Name: Testing WPBay SDK Integration
Description: Testing WPBay SDK
Version: 1.0.0
Author: WPBay
Text Domain: testing-plugin
*/

defined('ABSPATH') or die();

// Enable developer mode (optional)
define( 'WPBAY_TESTING-PLUGIN_DEVELOPER_MODE', true );
define( 'WPBAY_TESTING-PLUGIN_SECRET_KEY', 'MYSECRET-KEY' );

// Load and configure the WPBay SDK
if ( ! function_exists( 'testing_wpbay_sdk' ) ) 
{
    function testing_wpbay_sdk() 
    {
        require_once dirname( __FILE__ ) . '/wpbay-sdk/WPBay_Loader.php';

        global $wpbay_sdk_latest_loader;
        $sdk_loader_class = $wpbay_sdk_latest_loader;
        
        $sdk_params = array(
            'api_key'                 => 'MYA-API-KEY',
            'wpbay_product_id'        => '1337',
            'product_file'            => __FILE__,
            'activation_redirect'     => 'options-general.php?page=wpbay-settings',
            'is_free'                 => false,
            'is_upgradable'           => false,
            'uploaded_to_wp_org'      => false,
            'disable_feedback'        => false,
            'disable_support_page'    => false,
            'disable_contact_form'    => false,
            'disable_upgrade_form'    => false,
            'disable_analytics'       => false,
            'debug_mode'              => false,
            'rating_notice'           => '1 week',
            'no_activation_required'  => false,
            'menu_data'               => array(
                'menu_slug' => 'testing_admin_settings',
            ),
        );

        if ( class_exists( $sdk_loader_class ) ) {
            return $sdk_loader_class::load_sdk( $sdk_params );
        }
        return false;
    }

    // Initialize the SDK
    $sdk_instance = testing_wpbay_sdk();
    do_action( 'testing_wpbay_sdk_loaded', $sdk_instance );
}

// Register admin menu for plugin settings
add_action('admin_menu', 'testing_register_my_custom_menu_page');
add_action('network_admin_menu', 'testing_register_my_custom_menu_page');
function testing_register_my_custom_menu_page()
{
    $base_slug = 'testing_admin_settings';
    add_menu_page(
        'Testing',
        'Testing',
        'manage_options',
        $base_slug,
        $base_slug
    );
}

function testing_admin_settings()
{
    echo '<h1>Testing WPBay SDK Admin Page</h1>';
    echo '<p>Your custom admin settings go here.</p>';
}

// Custom error handler for deprecated notices
if ( ! function_exists( 'wpbay_custom_error_handler' ) ) 
{
    function wpbay_custom_error_handler($errno, $errstr, $errfile, $errline) {
        if (in_array($errno, [E_DEPRECATED, E_USER_DEPRECATED])) {
            $backtrace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 10);
            $trace_output = [];

            foreach ($backtrace as $index => $trace) {
                $file = isset($trace['file']) ? $trace['file'] : '(no file)';
                $line = isset($trace['line']) ? $trace['line'] : '(no line)';
                $function = isset($trace['function']) ? $trace['function'] : '(no function)';
                $trace_output[] = "#$index $file ($line): $function()";
            }

            $error_message = "PHP Deprecated: $errstr in $errfile on line $errline\nStack trace:\n"
                . implode("\n", $trace_output);
            
            error_log($error_message);
        }
        return false;
    }
    set_error_handler('wpbay_custom_error_handler');
}

That’s it! You have now integrated the WPBay SDK into your WordPress plugin. Feel free to adjust any parameters or add more customization as needed.

WPBay SDK Documentation

Table of Contents

1. Overview

Join the WPBay Community (Bonus)

The Quick Integration Guide

2. Requirements and Installation

3. Basic Integration Steps

3.1. Include the WPBay SDK in Your Plugin/Theme

WPBay SDK Configuration Generator

3.2. Debug Mode (Optional)

3.3. Developer Mode (Optional)

3.4. Configure SDK Parameters

3.5. Load the SDK

4. Understanding the SDK Parameters

5. Adding Settings/Registration Menus

6. Handling Updates & Activation

7. License Checks and Verification

7.1 License Verification Methods

`is_paid_or_trial_user()`

`is_not_paying_user()`

`is_trial_user()`

`is_paying_user()`

`is_plan($plan_name)`

7.2 Product Type Verification Methods

`is_theme()`

`is_plugin()`

7.3 Development and Debugging Modes

`is_developer_mode()`

`is_debug_mode()`

7.4 Manager Access Methods

`get_contact_form_manager()`

`get_upgrade_form_manager()`

7.5 Notes

8. Adding the Contact Form and Upgrade Form into your menus

9. Frequently Asked Questions (FAQ)

Example Integration in Full

Links

WPBay SDK Integration Documentation

WPBay SDK Documentation

Table of Contents

1. Overview

Join the WPBay Community (Bonus)

The Quick Integration Guide

2. Requirements and Installation

3. Basic Integration Steps

3.1. Include the WPBay SDK in Your Plugin/Theme

WPBay SDK Configuration Generator

3.2. Debug Mode (Optional)

3.3. Developer Mode (Optional)

3.4. Configure SDK Parameters

3.5. Load the SDK

4. Understanding the SDK Parameters

5. Adding Settings/Registration Menus

6. Handling Updates & Activation

7. License Checks and Verification

7.1 License Verification Methods

is_paid_or_trial_user()

is_not_paying_user()

is_trial_user()

is_paying_user()

is_plan($plan_name)

7.2 Product Type Verification Methods

is_theme()

is_plugin()

7.3 Development and Debugging Modes

is_developer_mode()

is_debug_mode()

7.4 Manager Access Methods

get_contact_form_manager()

get_upgrade_form_manager()

7.5 Notes

8. Adding the Contact Form and Upgrade Form into your menus

9. Frequently Asked Questions (FAQ)

Example Integration in Full

`is_paid_or_trial_user()`

`is_not_paying_user()`

`is_trial_user()`

`is_paying_user()`

`is_plan($plan_name)`

`is_theme()`

`is_plugin()`

`is_developer_mode()`

`is_debug_mode()`

`get_contact_form_manager()`

`get_upgrade_form_manager()`