FxFactory Developer

Table of Contents

The FxFactory Framework: Integrating External Code with FxFactory

Beginning with FxFactory 5.0.8, a new API allows any code executing on the system to interact with FxFactory. The primary goals of this API is to allow products that do not rely on the FxFactory runtime to do the following:

  1. Check on the registration status for a given product.
  2. Launch the FxFactory application to focus on a given product and/or initiate a purchase transaction.
  3. Bring up a Tech Support form pre-filled with information of your choice, to allow users to request assistance with your product through FxFactory.
  4. Check for new versions of your product, as advertised through our servers. In recent versions of FxFactory, this step is optional: as soon as your product checks for licensing status, FxFactory will automatically check for a new version of your software and allow users to begin the auto-update process.

A product is identified by its UUID, a unique identifier that allows various entities (our app, our plug-ins, our servers, and now your code too) to unequivocally identify each product available through FxFactory.

Checking for the licensing status of a product allows you to decide whether the product should run in trial mode or with its full feature set. Trial products may choose to render a watermark in its output, hide or limit certain functionality, etc.

When your code detects an error, your code can migrate any diagnostic information about the error to a new tech support contact form (for example: “An error occurred reading file X when processing a frame with plug-in Y.”) This allows for faster resolution of any problems users may encounter with your product.

The API described above is provided by the FxFactory.framework. This framework is available on your system as long as any recent version of our software is installed.

Linking against the FxFactory.framework

To get a copy of the FxFactory.framework, all you have to do is install a recent version of FxFactory. The framework’s install location is:

/Library/Frameworks/FxFactory.framework

Add this framework to your project, and make sure it is part of the link phase for the appropriate target (or targets) that will need to use our API. We recommend that you link to our framework weakly, allowing your code to run even if the FxFactory.framework is missing from the system1):

Weak-linking your code against the FxFactory framework requires a bit more setup work in Xcode. Refer to this page for a detailed explanation:

Frameworks and Weak Linking

Newer versions of Xcode give a more user-friendly way to link weakly to a framework. Add the framework to your project:

While the framework is selected, open the inspector and select “Optional” under the “Target Membership” section:

If your code weak-links to the FxFactory.framework, and its symbols cannot be resolved at runtime, one recommended approach would be to treat the product as in “Trial” and request the user to download a copy of FxFactory from our website.

Using the FxFactory.framework

If you hard-linked to the FxFactory framework, your code will cause an error when the framework is not installed on disk. If you weak-linked the FxFactory framework (as recommended), the linker will resolve all weak symbols automatically if the framework is installed. Symbols will remain NULL otherwise.

Remember to test you code with and without the FxFactory.framework. Drag the framework away from its install location to prevent it from being loaded by your code.

All API currently exposed by the framework is found in the “FxFactoryLicensing.h” header. It is a simple, C-based API. If you have weak-linked your code against the FxFactory framework, check for each function pointer to be non-NULL before invoking it2): 

#import <FxFactory/FxFactory.h>

FxFactoryLicensingStatus status = kFxFactoryLicensingStatusProductUnlicensed;

if ( FxFactoryGetLicensingStatus != NULL ) {
    status = FxFactoryGetLicensingStatus(...);
} else {
    // Remind user that FxFactory must be installed
}

if ( status == kFxFactoryLicensingStatusProductIsLicensed ) {
    // Product has been purchased.
}

Refer to the documentation in the header for an explanation of the API, the meaning of its parameters, and the meaning of the values returned by each function.

It is important to point out certain requirements and behaviors of the API:

  1. The UUID for your product must be assigned and agreed upon in preparation for your product’s distribution through FxFactory.
  2. The API will return meaningful results for any valid UUID. That is because it has no prior knowledge of which products may or may not exist in FxFactory, and this information is subject to constant change as our servers, app and website learn about each new product being released.3).
  3. The API is designed to be efficient, and it may not be necessary or desirable to cache its results. Beginning with FxFactory 7.1.1, the licensing status reported by FxFactoryGetLicensingStatus () may be updated while your app is running. If you wish to handle changes to the licensing status dynamically, refer to the new FxFactoryRegisterLicensingStatusHandler() API.
1)
The user may have uninstalled FxFactory, or deleted the framework by accident.
2)
Heed the warning contained in the official Apple documentation: use the explicit comparison against NULL rather than the ! operator, or else it will not work as expected
3)
If your code checks for the licensing status a non-existing product, the API would return a status of “Trial” forever, and any attempt to initiate a purchase transaction would fail.