Using the « Amazon Web Service Add-On » for delivery of Downloadable Products through the Amazon Cloud

The Add-On DownloadPlus for Amazon Web Services uses the Amazon Web Services SDK for PHP, and this requires the following preconditions on your Magento store installation to be fullfilled:

• The PHP interpreter, version 5.2 or newer. PHP 5.2.17 or 5.3.x is highly recommended for use with the AWS SDK for PHP.
• The cURL PHP extension (compiled with the OpenSSL libraries for HTTPS support).

Installation of the import adapter for DownloadPlus is the same as for the DownloadPlus extension itself.

The extension will allow to link files in a Amazon S3 bucket as the delivery in Downloadable Products.
The download link generated after purchase of the Downloadable Product is always a link to the Magento store itself. The purchased link is available in the customers account under “My Downloadable Products” just as a regular downloadable file uploaded to the store itself.

When the customer purchases his download, it is accessible from his customer account which means he will require to login prior to any later download.

For links to files residing on a Amazon S3 bucket a signed URL to the Amazon S3 object is being generated on the fly by the extension whenever a customer accesses the link to his purchased download.

The signed URL holds a download timeout meaning that URL is only good for a configurable amount of time as download. Upon actual download through the customer the customers browser is being redirected by the Magento Store to the temporary signed Amazon S3 URL and the browser starts the download from there. There is never a direct URL to the Amazon S3 Bucket objects being distributed, only a temporary signed URL for each customer download request on the original store generated URL on his purchase Downloadable Product.

To allow the DownloadPlus Add-On for Amazon Web Services to access the AWS API and exchange control and status messages you need to create an AWS User with the required minimum set of attached Security Policies as shown here now:

Login to your AWS Console: https://aws.amazon.com/console/home

Create a user using the AWS Management Console at http://aws.amazon.com/ in My Account » AWS Management Console: In the AWS Management Console select at the dropdown under your Account's Name » Security Credentials. Go to the IAM Management Console (or Get started with IAM Users when prompted) to add a User and related privileges to allow the AddOn access to the AWS resources:

Use Create new Users to create a new User, check the option Generate an access key for each user:

Create the new user, for the new user the Security Credentials are shown - either note or download the Security Credentials:

Use these credentials for the following configuration options of the Amazon Web Services Add-On:

• AWS Access Key
• AWS Secret Access Key

Now the new User shall show up in your accounts list of users:

Click on the new user account to get to its details:

Your new user account requires additional Policies to allow API Access for the Amazon Web Services Add-On, select and attach the following policies to the user account:

• AmazonS3FullAccess if you only want to integrate your AWS S3 Buckets with DownloadPlus for Magento
• CloudFrontFullAccess add this policy to the above if you also want to use CloudFront Distributions with DownloadPlus for Magento

Use Attach Policy to attach the selected policies to the user account, the user account should then show these policies as attached:

Now the newly created user has the sufficient privileges for access to your AWS resources. The credentials of this user account are then to be used for the configuration of the extension to access the buckets and files of your AWS S3 storage and to create and manage any CloudFront distribution you are using with this Add-On.

In case you lost the Access Credentials, or need to renew it because of security issues or that the API Access does not work correctly proceed like this:

Goto to the AWS User Account (open the AWS User details) in the AWS Management Console as shown above, open the section Security Credentials and use Manage Access Keys to view the current available keys, to inactivate or delete and to create a new one:

Use the new Access Key for the configuration of DownloadPlus for AWS in the options AWS Access Key and AWS Secret Access Key.

In your Magneto Stores Administrator Backend go to System » Configuration » Catalog » Downloadable Delivery through Amazon S3:

Enter the Access Credentials of the user you want to use to access your Amazon Web Services here as received from creating the related Amazon AWS user as documented here...

Enter the Secret Access Key from the Security Credentials of the User Account to use for access the Amazon Web Services and as received during creating the related Amazon AWS user as documented here...

Defined the timeout in minutes the download URL generated by the Amazon S3 service shall be valid for use. The Amazon Web Service for DownloadPlus extension retrieves a temporary download link from the Amazon S3 service whenever a customer wants to download his purchased Downloadable Product.

That generated download URL is only valid for the specified amount of time, and the customer accessing his download from your store will be automatically redirected there and the download from the Amazon S3 cloud starts.

Allows to set the HTTP-Header for Content-Disposition for the URL's pointing to the S3 Bucket Object that the Add-On is generating.

Allows to set the HTTP-Header for Cache-Control for the URL's pointing to the S3 Bucket Object that the Add-On is generating.

Using this cache mechanism allows to reduce outgoing requests to AWS improving speed in the Administrator Backend when editing Downloadable Products. Requests to AWS will get cached locally in var/cache/downloadplus-aws when enabled. Clear that directory in case you experience incorrect bucket lists when editing Downloadable Products.

Allows to set the schedule for automatic refreshing the Response Cache. A Magento CRON-Job will regularly pull the S3 Bucket Object List from the configured Buckets and save it locally on the Magento server. Change the update schedule in minutes. With having Response Caching set to be disabled this automatic update is disabled also.

Define the lifetime in minutes for the Response Cache, after this time period requests to AWS will refresh the Response Cache.

Adding a comma-separated list of bucket names here limits the bucket object selection at the Downloadable Product Link to these buckets. Use this option if you want to reduce the files in the select list to a single or a limited number of buckets.

Adding a regular expression here allows to add a PCRE Regular Expression (without starting and ending delimiter) that shall be applied to filter the buckets object list for the bucket object selection list at the Downloadable Product Link. Use this to narrow down the selectable files.

\.m3u8$

Allows to set the style for the bucket object selection to the following alternatives:

• Select Bucket Objects, enter File in textarea: Shows a dropdown with the S3 Buckets available, you enter the path and filename of the object into a text input field.
• Select File Objects: Shows a dropdown with all bucket file objects available, the dropdown allows to search for a file.

This is only show if you have already configured the AWS Access Key and AWS Secret Access Key, then access to the Amazon S3 buckets is tested and any results are shown here:

If Access to the Amazon S3 Buckets is correct (that includes the correctly set User Access Policies) a list of your S3 Buckets visible to the AWS Add-On is shown:

The extension checks if the current provided credentials and configuration options allow access to your Amazon S3 Buckets and that the communication to the Amazon AWS is working. Notifications on possible conflicts, or misconfiguration are shown here as well. This check is performed at page load, so when changing configuration option Save to save the options and the check will be performed at the page update with the saved configuration options.

To begin using the Amazon Web Service for DownloadPlus extension fill up one of your Buckets you have at the Amazon S3 service with the downloadable files you want to use with the Downloadable Products of your Magento Store:



Amazon Web Service for DownloadPlus will allow you to select a file from all of your Buckets and Folders you have on the Amazon S3 service.

Go to your Magento Store and edit or create the Downloadable Product as usually. Goto Downloadable Information and you will see that the Links and Samples section show a Amazon S3 drop-down option in addition to Links and Files:




Use that option to select the file you want to attach to your Downloadable Product and proceed in editing or creating your Downloadable Product as usually. The filenames are shown with the name of the bucket preceeding the folder/filename for each file available on your Amazon S3 storage:

That's it, your store is now able to deliver Downloadable Products from your Amazon S3 storage.

You may also use the following DownloadPlus features in combination with the delivery of files stored on the Amazon S3 storage:

• Creating Downloads with automatic expiration
• Adding Serialnumbers to Products

In order to be able to configure the Cloudfront Distribution of Media Files, first the Amazon S3 configuration as shown above is required to be made including creating the required AWS User and Account Policies. Create a source bucket on your Amazon S3 account that will hold the media files, upload the media files you want to use to that bucket.

In case your CloudFront Distribution shall use private content (that are time-restricted links to the media which generally prevent shared access to the media) then you need to create a CloudFront Key Pair: In the AWS Management Console select at the dropdown under your Account's Name » Security Credentials and select Continue to Security Credentials when prompted:

Open the CloudFront Key Pairs dropdown:

Select Create New Key Pair in the CloudFront Key Pairs section of the account overview:

Then Download the Private Key File of the newly created Key Pair to your computer:

• Copy and Paste the Access Key ID shown on the CloudFront Key Pair list for the newly created Key Pair to the configuration option CloudFront Access Key ID of the extension.
• Open the downloaded Private Key File with a text-editor and copy/paste the private key to the configuration option CloudFront Private Key of the extension.

The extension is now prepared to generated private access URL's for the media distributed with through Amazon Cloudfront.

To use a existing CloudFront Distribution, which is already configured using the AWS Management Console, simply select the Source-Bucket of that existing CloudFront Distribution in Amazon S3 Bucket for source and save the configuration.

The Add-On will read the configuration of the CloudFront Distribution for the selected Source-Bucket and will set its configuration options accordingly.

This Add-On is also able to create a new CloudFront Distribution, with all related privilege configuration, right from the configuration options of the Add-On. To select non-default settings on the edge locations, pricing options or logging options for the CloudFront Distribution created through the Add-On configuration, you need to use the AWS Management Console (see also Getting Started with CloudFront).

The following configuration options need to be set (and will then be locked when the CloudFront Distribution is created) to create a new CloudFront Distribution:

Select the Amazon S3 Bucket that holds the source files for the CloudFront Distribution. When choosing a bucket that has already a CloudFront Distribution associated, then the Add-On will configure the above options from the existing CloudFront Distributions configuration. To create a new CloudFront Distribution select a S3 Bucket here that currently has no associated CloudFront Distribution.

Select the type of Distribution:

• Download Distribution: Uses HTTP/HTTPS protocol for delivery of the media, this is the preferred type to use for Video pseudo-streaming (especially when needing delivery on iPhone, iPad or other mobile devices). See also Creating Download Distributions.
• Streaming Distribution: Uses RTMP streaming protocol for deliver of the media, with full streaming and seeking support for Video. Is not fully supported across mobile devices. See also Creating Streaming Distributions.

The Multimedia Players included in this Add-On support HTTP/HTTPS delivery, some also RTMP delivery of media.

Select if the URL's generated by the Add-On pointing to the Media files shall be:

• Public Access: Any URL's used on the generated browser page for viewing the content will be publicly accessible, meaning if someone shares that link access to the media source will be open to any other visitor as well.
• Private Access: Any URL's used on the generated browser page for viewing the content will be signed and only valid for a time period, such that sharing such link will prevent other access to the media file. This is especially recommended if you plan to deliver paid content through the CloudFront Distribution. See also Serving Private Content through CloudFront.

Allows to set what type of URL protocol (HTTP or HTTPS) shall be accepted by the CloudFront Distribution:

• All (insecure & secure): Allows access to resources on the distribution through HTTP (insecure) or HTTPS (secure) alike.
• Secure Only: Only allow to access the resources on the distribution through HTTPS (secure).

This setting only applies to a Download Distribution, for Streaming Distributions the RTMP protocol is used.

Save the current configuration, the related CloudFront Distribution will be created automatically. Allow your browser to complete the action, it may take a while for the process to complete.

You may then monitor the result CloudFront Distribution section where the status of the related CloudFront Distribution is shown then.

The CloudFront Distribution shows status information about the currently configured CloudFront Distribution:

With the following buttons management of the CloudFront Distribution is possible:

Disables the configured CloudFront Distribution. When wanting to delete the CloudFront Distribution it also needs to be disabled first.

Deletes the CloudFront Distribution, prior disabling it with Disable Distribution is required.

Updates the Access Privileges the CloudFront Distribution requires to be set on the S3 Source Bucket. In case a existing CloudFront Distribution is used this may be required, or if the CloudFront Distribution is not able to access the S3 source files.

Allows to update the configuration based on the current configuration of the CloudFront Distribution. Use this when making changes to the CloudFront Distribution through the AWS Management Console to get the configuration of the Add-On updated on them.

When using CloudFront as delivery network for purchased downloads, or for embedding media into the store and products pages, the Add-On is required to create URLs to link to the related file resource located on the CloudFront Distribution. This may cause security concerns, especially if you want to protect your files from being used by others than the individual customer.

When having a Private CloudFront Distribution, access to the resources there are only accessible with a signed URL. Whenever there is a request to your CloudFront Distribution that URL is checked for validity and access is given only for valid signed URLs. The URL Timeout option allows to set a lifetime for the signed URL, after which it expires.

To allow to configure the Add-On to the use required by your store implementation, the following configuration options allow what type of signed URL shall be used for the resources on your CloudFront Distribution:

Allows to set how to generate any signed URL (see also Overview of Signed URLs) that is pointing to a resource stored in the CloudFront Distribution:

• Insecure (http): Creates a signed URL with HTTP.
• Insecure (http) + IP-Address: Creates a signed URL with HTTP and the IP-Address of the remote referrer (the visitors IP-Address). CloudFront will then verify if the incoming URL-Request is coming from the same IP-Address that is set in the signed URL.
• Secure (https): Creates a signed URL with HTTPS.
• Secure (https) + IP-Address: Same as for Insecure (http) + IP-Address but with HTTPS.

Set the timeout in minutes for which the signed URL shall be valid. After this timeout the signed URL is taken as expired by the CloudFront Distribution.

The Add-On has the following Mediaplayers for Video and or Audio media files included, for details on the specific player please refer to the players origin site:

• Flowplayer: A HTML5 Player.
• JWPlayer: A HTML5 & Flash Player.
• Projekktor: A HTML5 Player with Flash fallback.
• Mediaelement: A HTML5 Player.
• VideoJS: A HTML5 Player.
• Custom Player: Allows to use your own mediaplayer implementation with the Add-On.

Some of the above player support HTTP (download distribution) and RTMP (streaming distribution) protocol, some only one of those. The list entry in the configuration option shows wich protocol is supported by the player, which must fit to the select type of CloudFront Distribution.

DownloadPlus for Amazon Web Services comes with a selected pool of Mediaplayers, targeted for showing Video file content.

Select the Media Player you want to use with the media files on your CloudFront Distribution. Not all included Mediaplayers support all Distribution Protocols, please refer to the Media Players Name where the supported distribution protocol is shown as part of the title.

If the MIME-Type of the associated file is of video/… or audio/… then the Mediaplayer is automatically used. For cases where the MIME-Type of the associated file is different, and you still want the Mediaplayer to handle the file, add the files extension here (without dots, comma separate multiple entries).

mp4,webm,flv

Allows to define a List of alternate filetypes used for the Media Player. So if you want to provide the same media content in multiple filetypes to the Media Player add the extensions here (without dots, comma separate multiple entries) in the order you want it to be:

mp4,webm,flv

Save your media files in all of the above filetypes and only select the first one for the Downloadable Link. The source filenames of all others will be derifed from the filename selected for the Downloadable Link:

Selected for Downloadable Link:
  my-media-content.mp4

List of resulting sources for the Media Player:
  my-media-content.mp4
  my-media-content.webm
  my-media-content.flv

If a particular source is not found in the Cloudfront Distributions underlying S3 Bucket, then the related source URL will not be generated for the Media Player. Only file sources found in the Source S3 Bucket will be included in the media source list of the Media Player.

Enter the display size of the Media Player, in WidthxHeight in pixels. If you want to use dynamic width (e.g. 50%) use the %-sign for the width or height you want to use as dynamic: e.g. 100%x600 (this may not work with all Mediaplayers).

If you have a license key for the selected Media Player, then enter it here.

To customize the Media Player use the template files that come with the Add-On:

1. The default Media Player templates are located in app/design/frontend/default/default/downloadplusaws/media/player (Frontend) and app/design/adminhtml/default/default/downloadplusaws/media/player (Administrator Backend) and are named in accordance with the Media Player source.
2. Copy the default Media Player template you want to customize to the same directory inside of your stores template location (for the Frontend or Backend) and name it custom.phtml.
3. Customize this new template to your liking.
4. Select Custom Player in the configuration option Media Player to now use the customized Media Player.

To implement your own Media Player source code create a new template file named custom.phtml in the template directory downloadplusaws/media/player of your stores frontend template, or in app/design/adminhtml/default/default/downloadplusaws/media/player for the Administrator Backend. See the default Media Player templates that come with the Add-On for the related template functions.

To use your own Media Player implementation select Custom Player in the configuration option Media Player to now use the customized Media Player.

You need to make a custom Media Player template for the Frontend AND the Administrator Backend.

You may add a media file to the Product Description using the following shortcode:

{{block type="downloadplusaws/amazon_cloudfront_media" name="product.description.media" file="...media file path and name here..."}}

Example:

{{block type="downloadplusaws/amazon_cloudfront_media" name="product.description.media" file="Videos/Were_NASA_and_We_Know_It_Mars_Curiosity.mp4"}}

Magento itself does not support shortcodes in the Product Description (or the Short Description), so the Add-On is having a Filter to which the description is to be handed over for rendering the required Mediaplayer code into it. That requires to modify the template file for the Product View Page as shown here:

<div class="product-specs">
<?php /*
	This is the original code:
	echo $this->helper('catalog/output')->productAttribute($this->getProduct(), $this->getProduct()->getDescription(), 'description') ?>
*/ ?>
<?php
	/* Use below code to render the Product Description, it feeds the description through a Filter for rendering the shortcode */
	$html = $this->helper('catalog/output')->productAttribute($this->getProduct(), $this->getProduct()->getDescription(), 'description');
	$html = Mage::helper('downloadplusaws/media')->doFilter($html);
	echo $html;
 ?>
</div>

You may use this approach to any other Attribute of the Magento Product as well.

To add a media file to a Downloadable Product simply select the file to add as downloadable item to the product with selecting the option Amazon CloudFront and selecting the file from the dropdown list if available files in the CloudFront Distribution:

To test the linked media file use Test URL which will open a new window with the Media Player for the selected CloudFront object, the URL to the CloudFront object is shown also:

Currently this Add-On does only support to view the media on the store site. Download of the media file through the CloudFront Distribution is not supported, if you need to distribute large downloadable files through the Amazon Web Services, please use the S3 Source-Bucket for the download as described in Adding the Amazon S3 download to your Downloadable Product above.

You may add a media file to the content of a CMS Page or a Static Block using the following shortcode:

{{block type="downloadplusaws/amazon_cloudfront_media" name="cloudfront.media" file="...media file path and name here..."}}

Example:

{{block type="downloadplusaws/amazon_cloudfront_media" name="cloudfront.media" file="Videos/Were_NASA_and_We_Know_It_Mars_Curiosity.mp4"}}

If you are using multiple CloudFront objects on the same page, make the name parameter unique to each object.

To use the Custom Design XML on a CMS Page to include the Media Player with a file from the CloudFront Distribution use this markup:

<block type="downloadplusaws/amazon_cloudfront_media" name="media.test">
    <action method="setData"><key>file</key><value>...media file path and name here...</value></action>
</block>
 
Example:
 
<block type="downloadplusaws/amazon_cloudfront_media" name="media.test">
     <action method="setData"><key>file</key><value>Videos/Were_NASA_and_We_Know_It_Mars_Curiosity.mp4</value></action>
</block>

Edit the related template file, load the desired Downloadable Link Model and use the following Block Code to insert the Media Player. See the following example to directly use the Media Player for Samples pointing to a Cloudfront Distribution object:

<?php $_samples = $this->getSamples() ?>
     <?php foreach ($_samples as $_sample):
         if ($_sample->getSampleType()==Pisc_DownloadplusAWS_Helper_Download::LINK_TYPE_AWSCF):
    	  	echo $this->getLayout()->createBlock('downloadplusaws/amazon_cloudfront_media')
        	    ->setSample($_sample)
        	    ->toHtml();
        else:
        ?>
            <dd>
                <a href="<?php echo $this->getSampleUrl($_sample) ?>" <?php echo $this->getIsOpenInNewWindow()?'onclick="this.target=\'_blank\'"':''; ?>><?php echo $this->escapeHtml($_sample->getTitle()); ?></a>
            </dd>
   <?php endif; ?>

echo $this->getLayout()->createBlock('downloadplusaws/amazon_cloudfront_media')
        	->setLink(/* Your Link model: e.g. $link */)
        	->toHtml();

echo $this->getLayout()->createBlock('downloadplusaws/amazon_cloudfront_media')
        	->setLinkSample(/* Your Link model: e.g. $link */)
        	->toHtml();

echo $this->getLayout()->createBlock('downloadplusaws/amazon_cloudfront_media')
        	->setSample(/* Your Sample model: e.g. $sample */)
        	->toHtml();

To use a custom player template add setTemplate('…template file…') to the createBlock method:

echo $this->getLayout()->createBlock('downloadplusaws/amazon_cloudfront_media')
        	->setSample($_sample)
                ->setTemplate('downloadplusaws/media/player/my-player.phtml')
        	->toHtml();