Difference between revisions of "Creating Digital Delivery Licensing Module"

From AbleCommerce Wiki
Jump to: navigation, search
(New page: To create a custom Digital Delivery Licensing Module you need to implement CommerceBuilder.DigitalDelivery.ISerialKeyProvider interface. This interface has been defined as follows. <code> ...)
 
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.
 
To create a custom Digital Delivery Licensing Module you need to implement CommerceBuilder.DigitalDelivery.ISerialKeyProvider interface. This interface has been defined as follows.
<code>
+
<code><pre>
 
     public interface ISerialKeyProvider
 
     public interface ISerialKeyProvider
 
     {
 
     {
Line 57: Line 57:
  
 
     }
 
     }
</code>
+
</pre></code>
  
 
The key methods to implement are AcquireSerialKey and ReturnSerialKey. The remaining methods/properties are mostly the same with slight differences for all implementations. Here is the code, slightly edited for this post, that shows how default serial key provider has been implemented.  
 
The key methods to implement are AcquireSerialKey and ReturnSerialKey. The remaining methods/properties are mostly the same with slight differences for all implementations. Here is the code, slightly edited for this post, that shows how default serial key provider has been implemented.  
  
<code>
+
<code><pre>
 
     public class DefaultSerialKeyProvider  
 
     public class DefaultSerialKeyProvider  
 
     {
 
     {
Line 141: Line 141:
 
         }
 
         }
 
     }
 
     }
 +
</pre>
 
</code>
 
</code>
  

Revision as of 18:21, 12 May 2008

To create a custom Digital Delivery Licensing Module you need to implement CommerceBuilder.DigitalDelivery.ISerialKeyProvider interface. This interface has been defined as follows.

    public interface ISerialKeyProvider
    {
        /// <summary>
        /// Name of the provider/module
        /// </summary>
        string Name { get; }

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

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

        /// <summary>
        /// The configuration URL where the provider/module 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 with this instance of the provider. This is passed during initialization.
        /// </summary>
        /// <returns>The DigitalGood object associated</returns>
        DigitalGood GetDigitalGood();

        /// <summary>
        /// The configuration data. Name value pairs.
        /// </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>
        /// Returns a serial key back to the provider store
        /// </summary>
        /// <param name="keyData">The key to return</param>
        void ReturnSerialKey(string keyData);

    }

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

    public class DefaultSerialKeyProvider 
    {
        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 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;
        }

        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 product. A digital good order is fulfilled when the serial key for the digital good order item is acquired. In the default implementation 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. This can happen, for example, if an order is canceled. In the default implementation the returned serial key is simply added to the available pool of serial keys for the digital good in question.