Creating Digital Delivery Licensing Module

ISerialKeyProvider

A Digital Delivery Licensing Module is required to implement CommerceBuilder.DigitalDelivery.ISerialKeyProvider interface. In version 7.0 final, this interface has been defined as follows.

    public interface ISerialKeyProvider
    {
        string Name { get; }

        string Version { get; }

        string Description { get; }

        string GetConfigUrl(System.Web.UI.ClientScriptManager cs);

        void Initialize(DigitalGood digitalGood, Dictionary<String, String> configurationData);

        // The digital good associated with this instance of the provider. This is passed during initialization.
        DigitalGood GetDigitalGood();

        Dictionary<string, string> GetConfigData();

        AcquireSerialKeyResponse AcquireSerialKey();

        void ReturnSerialKey(string keyData);
    }

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.

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.