Creating Digital Delivery Licensing Module

From AbleCommerce Wiki
Revision as of 17:27, 24 June 2009 by Loganr (Talk | contribs)

Jump to: navigation, search

Introduction

Sometimes merchants need to provide license keys as part of distribution of digital goods. AbleCommerce provides a built in license key module for simple requirements. With the built in provider, you provide a list of generated serial keys and AbleCommerce distributes keys from the list as needed.

If your licensing needs are more complicated, for example you must generate a key using specific order information, it is possible to implement a custom serial key provider to accomplish this functionality. Custom serial key providers can be plugged into AbleCommerce easily!

ISerialKeyProvider

Any custom licensing module is required to implement the CommerceBuilder.DigitalDelivery.ISerialKeyProvider interface. In version 7.0.3, this interface definition is given below for reference. It is possible to create a custom provider by implementing the interface, however this is NOT recommended. Custom providers should be created by extending the SerialKeyProviderBase class to insulate against future changes to the interface.

    /// <summary>
    /// Interface that must be implemented by digital delivery serial key providers
    /// </summary>
    public interface ISerialKeyProvider
    {
        /// <summary>
        /// Name of the provider
        /// </summary>
        string Name { get; }

        /// <summary>
        /// Implementation version
        /// </summary>
        string Version { get; }

        /// <summary>
        /// A description of the provider implementation
        /// </summary>
        string Description { get; }

        /// <summary>
        /// The configuration URL where the provider can be configured
        /// </summary>
        /// <param name="cs">ClientScriptManager</param>
        /// <returns>The configuration URL where the provider can be configured</returns>
        string GetConfigUrl(System.Web.UI.ClientScriptManager cs);

        /// <summary>
        /// Initializes the provider/module with the configuration data.
        /// </summary>
        /// <param name="digitalGood">The digital good</param>
        /// <param name="configurationData">The configuration data</param>
        void Initialize(DigitalGood digitalGood, Dictionary<String, String> configurationData);

        /// <summary>
        /// The digital good associated. Passed during initialization.
        /// </summary>
        /// <returns>The DigitalGood associated</returns>
        DigitalGood GetDigitalGood();

        /// <summary>
        /// The configuration data
        /// </summary>
        /// <returns>The configuration data</returns>
        Dictionary<string, string> GetConfigData();

        /// <summary>
        /// Acquires a new serial key from provider
        /// </summary>        
        /// <returns>Serial key acquisition response</returns>
        AcquireSerialKeyResponse AcquireSerialKey();

        /// <summary>
        /// Acquires a new serial key from provider
        /// </summary>
        /// <param name="oidg">OrderItemDigitalGood for which to acquire the key</param>
        /// <returns>Serial key acquisition response</returns>
        AcquireSerialKeyResponse AcquireSerialKey(OrderItemDigitalGood oidg);

        /// <summary>
        /// Returns a serial key back to the provider store
        /// </summary>
        /// <param name="keyData">The key to return</param>
        void ReturnSerialKey(string keyData);

        /// <summary>
        /// Returns a serial key back to the provider store
        /// </summary>
        /// <param name="keyData">The key to return</param>
        /// <param name="oidg">OrderItemDigitalGood the returned key is associated to</param>
        void ReturnSerialKey(string keyData, OrderItemDigitalGood oidg);

SerialKeyProviderBase

In order to implement a custom digital delivery module one approach could be to directly implement this interface. However, for the sake of easier future upgrades it is highly recommended that you implement your digital delivery licensing module by extending the abstract base class CommerceBuilder.DigitalDelivery.SerialKeyProviderBase.

Here is the code that shows how CommerceBuilder.DigitalDelivery.SerialKeyProviderBase has been defined.

    public abstract class SerialKeyProviderBase : ISerialKeyProvider
    {
        protected DigitalGood DigitalGood_;
        public DigitalGood GetDigitalGood() 
        {
            return DigitalGood_;
        }

        public virtual void Initialize(DigitalGood digitalGood, Dictionary<string, string> configurationData)
        {
            this.DigitalGood_ = digitalGood;
        }

        public virtual Dictionary<string, string> GetConfigData()
        {
            Dictionary<string, string> configData = new Dictionary<string, string>();            
            return configData;
        }

        public abstract string Name { get;}
        public abstract string Version { get;}
        public abstract string Description { get;}
        public abstract string GetConfigUrl(System.Web.UI.ClientScriptManager cs);

        public abstract AcquireSerialKeyResponse AcquireSerialKey();

        public abstract void ReturnSerialKey(string key);
    }

Implementing Required Methods

The major methods to implement are AcquireSerialKey and ReturnSerialKey. The remaining methods/properties are mostly the same with slight differences for various implementations. Here is the code, slightly edited for this post, that shows how default serial key provider has been implemented.

    public class DefaultSerialKeyProvider : SerialKeyProviderBase
    {
        public override string Name
        {
            get
            {
                return "Default Serial Key Provider";
            }
        }

        public override string Version
        {
            get
            {
                return "1.0";
            }
        }

        public override string Description
        { 
            get
            {
                return "Default Serial Key Provider";
            }
        }

        public override string GetConfigUrl(System.Web.UI.ClientScriptManager cs)
        {   
            return "DefaultProvider/AddKeys.aspx";
        }

        public override AcquireSerialKeyResponse AcquireSerialKey()
        {
            AcquireSerialKeyResponse response = new AcquireSerialKeyResponse();
            if (DigitalGood_.SerialKeys.Count > 0)
            {
                SerialKey key = DigitalGood_.SerialKeys[0];
                DigitalGood_.SerialKeys.RemoveAt(0);         
                string keyData = key.SerialKeyData;
                key.Delete();
                response.Successful = true;
                response.SerialKey = keyData;
                return response;
            }
            else
            {
                response.ErrorMessage = "There are no serial keys available for the digital good '" + DigitalGood_.Name + "'";
                return response;
            }
        }

        public override void ReturnSerialKey(string keyData)
        {
            if (!string.IsNullOrEmpty(keyData))
            {
                SerialKey skey = new SerialKey();
                skey.SerialKeyData = keyData;
                skey.DigitalGoodId = DigitalGood_.DigitalGoodId;
                skey.Save();
            }
        }
    }

It is quite easy to understand what most of the above methods are about. We will have a closer look at GetConfigUrl, AcquireSerialKey and ReturnSerialKey.

GetConfigUrl method gets the URL relative to Admin/Products/DigitalGoods/ folder in AbleCommerce 7 installation. The configuration URL is the place where you are taken to when you click on 'Configure' link when setting a serial key provider for a digital good. On the configure page it is up to the provider implementation to do whatever is appropriate for the given requirements. The default implementation takes you to AddKeys.aspx page where you can associate keys to the digital product you are configuring. Default implementation offers you to provide serial keys manually. In your custom implementation you may chose some arbitrary method of associating keys to a digital good.

Serial Key Provider 'Configure' Link


AcquireSerialKey is the method responsible for acquiring a serial key for a digital good that has been purchased. It gets the key from the pool of available serial keys for the given digital good product. A digital good order is fulfilled when the serial key for the corresponding order item digital good is acquired. In the default implementation of AcquireSerialKey we simply return the next available serial key for the digital good in question.


The ReturnSerialKey method is used to return a serial key back to the pool of available serial keys so that it can be reused. This can happen, for example, if an order is canceled. In the default implementation of ReturnSerialKey, the returned serial key is simply added to the available pool of serial keys for the digital good in question.


Deployment

Once you have completed the implementation code you need to compile your classes and put the resulting DLL in Bin folder of your Ablecommerce installation. Once your DLL is placed in the Bin folder, Ablecommerce will automatically detect your new serial key provider and show it in the Serial Key Provider drop-down on add/edit digital good page.

Resources