Difference between revisions of "Creating Digital Delivery Licensing Module"

From AbleCommerce Wiki
Jump to: navigation, search
m
Line 1: Line 1:
To create a custom Digital Delivery Licensing Module you need to implement '''CommerceBuilder.DigitalDelivery.ISerialKeyProvider''' interface. This interface has been defined as follows.
+
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.
 
<code>
 
<code>
 
<pre>
 
<pre>
Line 26: Line 26:
 
</code>
 
</code>
  
The key 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.  
+
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 this interface by extending the abstract base class '''CommerceBuilder.DigitalDelivery.SerialKeyProviderBase'''.
  
<code><pre>
+
Here is the code that shows how '''CommerceBuilder.DigitalDelivery.SerialKeyProviderBase''' has been defined.
     public class DefaultSerialKeyProvider : ISerialKeyProvider
+
<code>
 +
<pre>
 +
     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);
 +
    }
 +
</pre>
 +
</code>
 +
 
 +
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.
 +
 
 +
<code>
 +
<pre>
 +
    public class DefaultSerialKeyProvider : SerialKeyProviderBase
 
     {
 
     {
 
         public override string Name
 
         public override string Name
Line 58: Line 95:
 
         {   
 
         {   
 
             return "DefaultProvider/AddKeys.aspx";
 
             return "DefaultProvider/AddKeys.aspx";
        }
 
 
        public virtual void Initialize(DigitalGood digitalGood, Dictionary<string, string> configurationData)
 
        {
 
            this.DigitalGood_ = digitalGood;
 
        }
 
 
        protected DigitalGood DigitalGood_;
 
        public DigitalGood GetDigitalGood()
 
        {
 
            return DigitalGood_;
 
        }
 
 
        public virtual Dictionary<string, string> GetConfigData()
 
        {
 
            Dictionary<string, string> configData = new Dictionary<string, string>();           
 
            return configData;
 
 
         }
 
         }
  
Line 108: Line 128:
 
         }
 
         }
 
     }
 
     }
 +
 
</pre>
 
</pre>
 
</code>
 
</code>

Revision as of 11:52, 26 August 2008

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);
    }

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 this interface 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);
    }

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.