App Integration

This guide covers integrating an application that includes a license activation flow. Examples include desktop apps (macOS or Windows), Chrome extensions, Electron apps, and more.

Initial Steps

1. Sign up for Freemius
2. Create a new App product
3. Configure your plans and pricing in the Plans section

Checkout Integration

There are multiple ways to integrate Checkout within your marketing page or directly within your app.

Marketing or Pricing Page

Use the Freemius Checkout JavaScript SDK or Buy Button to embed the checkout. The flow is as follows:

1. Buyers purchase from your website.
2. Freemius sends them a license key.
3. They use the license key to activate your app.

In-App Purchase

If your app is web-based, you can use the same Buy Button API. We also provide an NPM package to load the Checkout.

For other cases, you can open the Freemius Checkout directly. To generate checkout links, go to the Plans page and click on the “Get Checkout” button. Here’s an example link:

https://checkout.freemius.com/app/{product_id}/plan/{plan_id}/

Testing Checkout Integration

Freemius allows you to make sandbox purchases. If you just want to make a purchase:

1. Go to Plans and click on “Get Checkout” button.
2. Select the Sandbox link.
3. Fill the form and use any test card or test PayPal account
4. Make sure to use an email address you have access to.
5. Once the purchase is made you will receive an email with a license key in it.

If you want to test sandbox payments within your application, then you can use the following logic to generate the sandbox token.

import crypto from 'crypto';

const productId = '<<productID>>';
const planId = '<<planID>>';
const productPublicKey = '<<publicKey>>';
const productSecretKey = '<<secretKey>>';
const timestamp = Math.floor(Date.now() / 1000);

const sandboxToken = crypto
	.createHash('md5')
	.update(
		`${timestamp}${productId}${productSecretKey}${productPublicKey}checkout`
	)
	.digest('hex');

// If using direct links
const checkoutLink = `https://checkout.freemius.com/app/${productId}/plan/${planId}/?sandbox=${sandboxToken}&s_ctx_ts=${timestamp}`;
console.log(checkoutLink);

// If using the Buy Button API
fsCheckout.open({
	sandbox: {
		token: sandboxToken,
		ctx: timestamp,
	},
});

Integrating Users

If you already have the user’s email address from your app or website, pass the following parameters in the Buy Button SDK:

1. user_email: The user’s email address
2. readonly_user: true

For a direct checkout link, add these parameters as query strings:

https://checkout.freemius.com/app/{product_id}/plan/{plan_id}/?user_email={email}&readonly_user=true

The checkout will enforce the provided email address when the user makes a purchase.

License Activation

Upon purchase, Freemius sends the buyer a license key via email.

• If using in-app Checkout integration, you can auto-activate the license after purchase.
• Otherwise, provide a UI for users to enter their license key manually.

Once the key is entered, follow this guide to learn how to activate and manage licenses from your app.

• License activation
• License deactivation
• License validation

Webhook Integration (Optional)

For more advanced workflows you can integrate with Freemius’ Webhook. There are endless number of things you can do with webhooks, here are a few examples:

Auto activate license

1. A user makes a purchase from your application.
2. Your webhook receives a license.created event with the license and buyer details.
3. Your webhook sends a push to the relevant connected application.
4. The application gets and activates the license.

Sync license with application

1. Your webhook receives a license.plan.changed, license.extended, license.shortened, license.expired, license.deleted, license.cancelled event.
2. It sends a push to the relevant connected application.
3. The application synchronises the license.

Send payment notification

1. Your webhook receives a payment.created event.
2. It sends a relevant push notification to your app.
3. Your app shows a notification to your user that a payment was received.

Here’s some sample integration code that you can use to make your own workflow.

import crypto from 'crypto';
import express from 'express';
import bodyParser from 'body-parser';

const app = express();
const PRODUCT_SECRET_KEY = '<PRODUCT_SECRET_KEY>';

app.post('/webhook', bodyParser.raw({ type: '*/*' }), (req, res) => {
	const input = req.body.toString('utf8');
	const hash = crypto
		.createHmac('sha256', PRODUCT_SECRET_KEY)
		.update(input)
		.digest('hex');
	const signature = (req.headers['x-signature'] as string) || '';

	// Verify the signature and authenticity of the webhook event.
	if (hash !== signature) {
		res.status(200).send();
		return;
	}

	const fsEvent = JSON.parse(input);

	processEvent(fsEvent);
});

app.listen(3000, () => {
	console.log('Server is listening on port 3000');
});

function processEvent(fsEvent) {
	let appInstances;

	switch (fsEvent.type) {
		case 'license.created':
            appInstances = myApp().findByExternalUser(fsEvent.objects.user);

			// Send push to the app to auto activate the license
			myApp().pushService(appInstances).sendActivationNotice(
				fsEvent.objects.license
			);
			break;

		// Synchronize license
		case 'license.plan.changed':
		case 'license.extended':
		case 'license.shortened':
		case 'license.expired':
		case 'license.deleted':
		case 'license.cancelled':
			appInstances = myApp().findByExternalLicenseId(fsEvent.objects.license.id);

            myApp().pushService(appInstances).sendSyncSignal();
            break;

		case 'payment.created':
            appInstances = myApp().findByExternalLicenseId(fsEvent.data.license_id);

			// Send push to the app to update the payment status
			myApp().pushService(appInstances).sendPaymentNotice(fsEvent.objects.payment);
			break;
	}
}

Other Integrations

• For Customer Portal, see this guide.
• To customize the style of the Checkout please follow this guide.

You can always navigate to the Setup Checklist page to find out what you need to do next to set up your application. If you have any questions, please feel free to contact our support.