The FlickRocket platform consists of a shop frontend, an access backend, administration, preparation and client side modules. This document explains how to replace the shop frontend with a custom shop system while maintain all the functionality of the other modules.
The functionalities of the different modules are a follows:
Module |
Responsibility |
Shop Frontend |
|
Access Backend |
Enables the customer to access content by requesting software to be installed (if required) and offering access functionality using the installed software. |
Administration |
Enables the content owner to manage the content, licenses, pricing and all related shop functionality. |
Preparation |
Enables the customer to ingest content into the platform and does the required content preparation steps to support all different platforms. |
Client Side |
Works based on the Access Backend and enables the customer to access purchased content. |

The shop frontend can be replaced by different shop systems. However, it is important to understand that these shop frontends should have at least the following options for being able to be used as replacement:
- Needs to be able to present different license options (e.g. rental and purchase) for products
- Needs to offer a login function for existing customers (the access to the content is managed by FlickRocket).
- Needs support for SSL to accept payments
- Needs to be able to use SOAP requests to communicate with the FlickRocket Access Backend
- Customers must be forced to specify at least an email and password
The following explains the web services which must be used to integrate the custom shop frontend with the FlickRocket platform.
URLs
The FlickRocket OnDemandOrder web service (SOAP) can be accessed at the URLs below. We provide C# sample code but PHP may also be used.
Service URL: https://www.flickrocket.com/Services/OnDemandOrder/service.asmx
Service WSDL: https://www.flickrocket.com/Services/OnDemandOrder/service.asmx?WSDL
Shop Related Web Service Functions
Shop Related Web Service functions are functions which work based on a Shop user which is granted access to individual content items and licenses.
CheckAccount()The CheckAccount function checks if the account data is valid and can access a certain theme.
bool CheckAccount(string EMail, string Password, int ThemeID, out int ErrorCode)
Return value |
Returns true on success |
|
FlickRocket admin user email (requires “shop management” right) |
Password |
FlickRocket admin user password |
ThemeID |
The identifier of a theme. Themes are used by other API functions and are defined in the FlickRocket web interface. ID 1 is a default theme which is accessible to all users. |
ErrorCode |
Out Param Returns an ErrorCode if CheckAccount failed: -1: FlickRocket User not found -2: FlickRocket User valid but theme does not exist -3: FlickRocket User valid but has no access rights to theme -4: API not enabled |
CreateShopOrder()
The CreateShopOrder function is used to communicate new content rights for a user to the FlickRocket platform. Basically the rights can be specified in of two ways:
By specifying the content and associated license
This is typically used for shop integration in which the user has selected and paid for content). The Items node is used to specify content and associated license. If it is empty, it can also be used to create just a new user.
By specifying one or more UnlockCodes to be redeemed
This is typically used for scenarios where a web site offers code redemption. The UnlockCodes node is used to specify UnlockCodes to be redeemed.
CreateShopOrder may only the used with one of the before mentioned options at a time. Using multiple will result in an error.
bool CreateShopOrder(string EMail, string Password, string XML, out int ErrorCode)
Return value |
Returns true on success |
|
FlickRocket admin user email (requires “shop management” right) |
Password |
FlickRocket admin user password |
XML |
XML formatted content/rights, group information or UnlockCodes |
ErrorCode |
Out Param Returns an ErrorCode if CreateShopOrder failed: -1: FlickRocket User not found -2: Malformed XML -3: “Order” Root in XML not found -4: Wrong email or password in XML -5: Unknown Error -6: No Customer Password in XML -7: Invalid UnlockCode(s) -8: Expired UnlockCode(s) -9: UnlockCode(s) usage exceed -10: API Usage not allowed. Please contact FlickRocket. -11: Invalid project -12: Project deleted -13: New user cannot be created with PasswordHash -14: No permission to create order for this product -15: Double order |
The XML must be constructed as follows:
Node Identifier | Value Type | Description |
---|---|---|
Order |
||
TransactionID |
Alphanumeric (Mandatory) |
TransactionID (supposed to be unique) to map this order in FlickRocket with an order in the 3rd party shop frontend. The TransactionID is reported in the CSV exports. |
|
Email (Mandatory) |
The email address of the customer. To access the content via the Access Backend or Client Side software, this email needs to be used. |
Password |
Alphanumeric (Optional) |
The clear text password of the customer. To access the content via the Access Backend or Client Side software, this password needs to be used. For new customers this field must be used. “Password” or “PasswordHash” needs to be present in the XML. |
PasswordHash |
Alphanumeric (Optional) |
The SHA-1 password of the customer. To access the content via the Access Backend or Client Side software, this password needs to be used. For existing customers this field or the plain text Password might be used. “Password” or “PasswordHash” needs to be present in the XML. |
ThemeID |
Numeric (Mandatory) |
The ThemeID of the theme to be associated with the order. On company may have multiple themes with different content. For any web interface design elements the user is presented, this theme is used. The ThemeIDs are listed in the FlickRocket admin interface under Shop -> Themes -> Manage design and texts. |
Firstname | Alphanumeric (Optional) | First name of the customer |
Lastname | Alphanumeric (Optional) | Last name of the customer |
Address1 | Alphanumeric (Optional) | Address of the customer |
Address2 | Alphanumeric (Optional) | Additional address information |
City | Alphanumeric (Optional) | City |
ZIP | Alphanumeric (Optional) | ZIP code |
State | Alphanumeric (Optional) | State for US/CA only. Specified in two characters, e.g. "CA" for Califonia |
Country | Alphanumeric (Optional) | The two character country code. E.g. "US" for United States |
Language | Alphanumeric (Optional) | The two character language code. E.g. "en" for English |
Items |
Item Node (Optional) |
A list of item nodes which define the actual ordered items and associated licenses. |
Item |
If no Items node is present, only the user is created on the FlickRocket platform. |
|
ProjectID |
ProjectID (Mandatory) |
The ProjectID of the content. The format of ProjectIDs is always ABCD-ABCD-ABCD-ABCD and a list of all ProjectIDs are listed under Projects -> List projects. |
LicenseID |
The LicenseID of the content. The LicenseIDs are listed under Shop -> Licenses -> List licenses. |
|
Count |
Numeric (Mandatory) |
The number of ordered licenses for the project. |
HD |
Numeric (Optional) |
Must be “1” if the content is video and the HD version is ordered. Muist be “0” if the content is video and the SD version is ordered. |
|
||
UnlockCodes |
UnlockCode Node (Optional) |
A list of UnlockCodes to be redeemed. |
UnlockCode |
Alphanumeric (Mandatory) |
One Unlockcode to be redeemed |
Sample XML for items:
Sample XML for items:
<?xml version="1.0" encoding="utf-8" ?><?xml version="1.0" encoding="utf-8" ?>
<Order>
<TransactionID>001</TransactionID>
<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!;/EMail>
<Password>password</Password>
<!-- <PasswordHash> </PasswordHash> --> <!-- SHA1 Encrypted, only for existing customers -->
<ThemeID>32</ThemeID>
<Items> <!—- Optional: If not included only a customer will be created -->
<Item>
<ProjectID>0000-1C80-33B9-7A42</ProjectID>
<!-- The project to be ordered with this item. Can be found in the web interface. -->
<LicenseID>16</LicenseID>
<!-- Identifies the license to be used for the order. Can be found in the web interface. -->
<Count>1</Count>
</Item>
<Item>
<ProjectID>0000-1B18-685F-0DD8</ProjectID>
<!-- The project to be ordered with this item. Can be found in the web interface. -->
<LicenseID>19</LicenseID>
<!-- Identifies the license to be used for the order. Can be found in the web interface. -->
<Count>1</Count>
</Item>
</Items>
</Order>
or sample XML for UnlockCode redemption:
<?xml version="1.0" encoding="utf-8" ?><?xml version="1.0" encoding="utf-8" ?>
<Order>
<TransactionID>001</TransactionID>
<EMail> Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!;;/EMail>
<Password>password</Password>
<!-- <PasswordHash> </PasswordHash> --> <!-- SHA1 Encrypted -->
<ThemeID>32</ThemeID>
<UnlockCodes>
<UnlockCode>ABCD-ABCD-ABCD-ABCD</UnlockCode>
<UnlockCode>BCDE-BCDE-BCDE-BCDE</UnlockCode>
</UnlockCodes>
</Order>
CheckUserExists()
The CheckUserExists function is used to check if a user is already known to the backend. This is usually done in advance of calling the CreateShopOrder function to make sure the user is valid.
The function returns true if the email address is unknown or the email address is known and the password matches. In both cases the CreateShopOrder function can be used with the identical email and password.
The function returns false in case of an error. In case the ErrorCode is -5 the email is known to the backend but the password does not match. In this case the calling application should display a message to the user that his email is already known from his purchases in the shop list returned in the Companies parameter and he has to use the matching password.
bool CheckUserExists(string EMail, string Password, string XML, out int ErrorCode, out List<string> Companies)
Return value | Returns true if the email address is unknown or the email address is known and the password matches |
FlickRocket admin user email (requires “shop management” right) | |
Password | FlickRocket admin user password |
XML | XML formatted user data |
ErrorCode |
Out Param Returns an ErrorCode if CheckUserExists failed: -1: Invalid User -2: Malformed XML -3: Customer Node not found -4: Password or PasswordHash Node not found -5: Email found but wrong Password. The companies from which the user data is known is available in the Companies parameter -6: Empty user password |
The XML must be constructed as follows:
Node Identifier | Value Type | Description |
---|---|---|
Customer |
||
|
Email (Mandatory) |
The email address of of the customer to be checked. |
Password |
Alphanumeric (Optional) |
The clear text password of the customer. “Password” or “PasswordHash” needs to be present in the XML. |
PasswordHash |
Alphanumeric (Optional) |
The password hash of the customer. “Password” or “PasswordHash” needs to be present in the XML. |
Sample XML:
<?xml version="1.0" encoding="utf-8" ?>
<Customer>
<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/EMail>
<Password>password</Password>
<!-- <PasswordHash>a1</PasswordHash> --> <!-- SHA1 Encrypted -->
</Customer>
CheckPreviewExists()
The CheckPreviewExists function is used to check if a preview/trailer exists for the specified project. The function returns true if a preview exists and false if no preview exists.
If a preview exists, it can be played back by navigating (typically in a pop up) to the following link with passing the ProjectID.
http://www.flickrocket.com/services/OnDemandOrder/Preview.aspx?PID=<ProjectID>
bool CheckPreviewExists(string EMail, string Password, string ProjectID)
Return value |
Returns true if a preview exists and false if no preview exists |
|
FlickRocket admin user email (requires “shop management” right) |
Password |
FlickRocket admin user password |
ProjectID |
The ProjectID of the project for which the preview availability is checked |
Sample URL:
http://www.flickrocket.com/services/OnDemandOrder/Preview.aspx?PID=ABCD-ABCD-ABCD-ABCD
ChangeCustomerPassword()
The ChangeCustomerPassword function is used to update the FlickRocket platform with an updated password in case the user changes his password.
In case the original password is not known (e.g. for a “forgotten password” function) where the user is externally verified (e.g. by sending an email with a confirmation link) the function can be used with the magic value “_use_only_after_external_validation_” as original password parameter. However, this works only if the company using the API has created the user or has sold items to the user. THIS MUST NOT BE USED FOR REGULAR PASSWORD CHANGES.
bool ChangeCustomerPassword(string EMail, string Password, string XML, out int ErrorCode)
Return value |
Returns true on success |
|
FlickRocket admin user email |
Password |
FlickRocket admin user password (requires “shop management” right) |
XML |
Formatted user data |
ErrorCode |
Out Param Returns an ErrorCode if ChangeCustomerPassword failed: -1: FlickRocket user not found -2: Malformed XML -3: “Customer” Root in XML not found -4: Customer user not found -5: No Password or PasswordHash in XML -6: No NewPassword or NewPasswordHash in XML -7: New PasswordHash not supported |
The XML must be constructed as follows:
Node Identifier | Value Type | Description |
---|---|---|
Customer |
||
|
Email (Mandatory) |
The email address of of the customer for which the password is changed. |
Password |
Alphanumeric (Optional) |
The old clear text password of of the customer (for regular passord changes) or “_use_only_after_external_validation_” if the orginal password is unknown and the email has been externally validated, e.g. by sending an email with a confirmation link. “Password” or “PasswordHash” needs to be present in the XML. |
NewPassword |
Alphanumeric (Optional) |
The new clear text password of the customer. “NewPassword” or “NewPasswordHash” needs to be present in the XML. |
PasswordHash |
Alphanumeric (Optional) |
The old SHA-1 password of the customer. “Password” or “PasswordHash” needs to be present in the XML. |
Sample XML for regular password change:
<?xml version="1.0" encoding="utf-8" ?>
<Customer>
<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/EMail>
<Password>password</Password>
<NewPassword>newpassword</NewPassword>
<!-- <PasswordHash>a1</PasswordHash> --> <!-- SHA1 Encrypted -->
</Customer>
Sample XML for password reset after external email validation:
<?xml version="1.0" encoding="utf-8" ?>
<Customer>
<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/EMail>
<Password>_use_only_after_external_validation_</Password>
<NewPassword>newpassword</NewPassword>
<!-- <PasswordHash>a1</PasswordHash> --> <!-- SHA1 Encrypted -->
</Customer>
ChangeCustomerEmail()
The ChangeCustomerEmail function is used to update the FlickRocket platform with an updated email in case the user changes his email.
bool ChangeCustomerEmail(string EMail, string Password, string XML, out int ErrorCode)
Return value |
Returns true on success |
|
FlickRocket admin user email |
Password |
FlickRocket admin user password (requires “shop management” right) |
XML |
Formatted user data |
ErrorCode |
Out Param Returns an ErrorCode if ChangeCustomerEmail failed: -1: Invalid user -2: Invalid XML -3: Customer node in XML not found -4: Customer not found -5: Password node in XML not found -7: New email node in XML not found -8: New email already exists |
The XML must be constructed as follows:
Node Identifier | Value Type | Description |
---|---|---|
Customer |
||
|
Email (Mandatory) |
The email address of the customer for which the email is changed. |
NewEMail |
Email (Mandatory) |
|
Password |
Alphanumeric (Optional) |
The clear text password of the customer. “Password” or “PasswordHash” needs to be present in the XML. |
PasswordHash |
Alphanumeric (Optional) |
The SHA-1 password of the customer. “Password” or “PasswordHash” needs to be present in the XML. |
Sample XML:
<?xml version="1.0" encoding="utf-8" ?>
<Customer>
<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/EMail>
<NewEMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/NewEMail>
<Password>password</Password>
<!--<PasswordHash>a1</PasswordHash>--> <!-- SHA1 Encrypted -->
</Customer>
PrepareLoginEx()
The PrepareLoginEx function is used to get a unqiue URL for the Access Backend which can be embedded via iframe or to which the user can be redirected after purchase or at login.
bool PrepareLoginEx(string EMail, string Password, string XML, int ThemeID, out int ErrorCode, out string sURL)
Return value |
Returns true on success |
|
FlickRocket admin user email (requires “shop management” right) |
Password |
FlickRocket admin user password |
XML |
XML formatted user description |
ThemeID |
The Id of the theme to be used |
ErrorCode |
Out Param Returns an ErrorCode if PrepareLogin failed: -1: FlickRocket user not found -2: Malformed XML -3: “Customer” root in XML not found -4: Customer user not found -5: Email and password do not match -6: Invalid theme |
sURL |
Returns a URL to be embedded via iframe or to be redirected to. |
The XML must be constructed as follows:
Node Identifier | Value Type | Description |
---|---|---|
Customer |
||
|
Email (Mandatory) |
The email address of the customer who should be logged in. |
Password |
Alphanumeric (Optional) |
The clear text password of the customer. “Password” or “PasswordHash” needs to be present in the XML. |
PasswordHash |
Alphanumeric (Optional) |
The SHA-1 password of the customer. “Password” or “PasswordHash” needs to be present in the XML. |
Sample XML:
<?xml version="1.0" encoding="utf-8" ?>
<Customer>
<EMail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!<;/EMail>
<Password>password</Password>
<!-- <PasswordHash>a1</PasswordHash> --> <!-- SHA1 Encrypted -->
</Customer>
GetProjects()
The GetProjects function is used to retrieve a list of projects. The function returns true if a valid list of projects is returned.
bool GetProjects (string EMail, string Password, int ThemeID, out List<string> Projects, out int ErrorCode)
Return value |
Returns true if the list of projects is returned and can be used |
|
FlickRocket admin user email (requires “shop management” right) |
Password |
FlickRocket admin user password |
ThemeID |
The ThemeID to which the projects needs to be assigend which will be returned back. If theme is -1, all projects are returned. |
Projects |
Out Param For each project the following structure is returned: public struct stProject { public string LongProjectID; public string Name; public DateTime CreationDate; public eContentType ContentType; public bool Complete; } public enum eContentType { Unknown = -1, fluxDVD = 1, Silverlight = 2, //Reserved WebProject = 3, Software = 4, AudioCollection = 5, Physisch = 6, //Physical item fluxPackage = 7, ProjectCollection = 8, fluxDVD_HD = 9, SmartTV_Video = 10, //Reserved SmartTV_Audio = 11, //Reserved ProjectBased = 15, //Reserved eBook = 16, } |
ErrorCode |
Out Param Returns an ErrorCode if GetProjects failed: -1: Invalid User -2: No projects found -3: Unknown error |
GetLicenses()
The GetLicenses function is used to retrieve a list of licenses. The function returns true if a valid list of licenses is returned.
bool GetProjects (string EMail, string Password, out List<stLicense> Licenses, out int ErrorCode)
Return value |
Returns true if the list of licenses is returned and can be used |
|
FlickRocket admin user email (requires “shop management” right) |
Password |
FlickRocket admin user password |
Licenses |
For each license the following structure is returned: publicstructstLicense { publicint ID; publicstring Name; } |
ErrorCode |
Out Param Returns an ErrorCode if GetLicenses failed: -1: Invalid User -2: No licenses found -3: Unknown error |
GetThemes()
The GetThemes function is used to retrieve a list of themes. The function returns true if a valid list of themes is returned.
bool GetThemes (string EMail, string Password, out List<stTheme> Themes, out int ErrorCode)
Return value |
Returns true if the list of themes is returned and can be used |
|
FlickRocket admin user email (requires “shop management” right) |
Password |
FlickRocket admin user password |
Themes |
Out Param For each license the following structure is returned: public struct stTheme { publicint ID; publicstring Name; public string Domain; public string Settings; } |
ErrorCode |
Out Param Returns an ErrorCode if GetThemes failed: -1: Invalid User -2: No themes found -3: Unknown error |
GetTrailer()
The GetTrailer function is used to retrieve a list of trailers for projects. Please note that trailers are optional and may not exist. If a trailer does not exist, it is not returned as part the stTrailers list. The function returns true if a valid list of trailers is returned.
bool GetTrailer (string EMail, string Password, List<string> ProjectIDs, out List<stTrailer> Trailer, out int ErrorCode)
Return value |
Returns true if the list of trailers is returned and can be used |
|
FlickRocket admin user email (requires “shop management” right) |
Password |
FlickRocket admin user password |
ProjectIDs | A list of the ProjectIDs for wich trailers should be returned. If no ProjectID is specified, all trailers are returned. |
Trailer |
Out Param For each trailer the following structure is returned: public struct stTrailer { public string URL; public string ProjectID; } |
ErrorCode |
Out Param Returns an ErrorCode if GetTrailer failed: -1: Invalid User -2: No trailer(s) found -3: Unknown error |
User data changes syncback
The following describes the process how FlickRocket communicates user information changes (E-Mail/Password changes) to 3rd party shop platforms which are related to the user whose information is updated.
To utilize this functionality, a number of settings has to be done in the related App Settings of the FlickRocket Backend. This is done in the admin interface under Extensions / Mage Apps / <Settings for the App>.
Setting | Description |
UserDataChangeURL | The URL to which the change notifications get requests are sent. |
Hash Type | The type of the password has to be communicated for password changes. |
Secret | The secret to be used for signing the request. This must also be known on the receiving end. |
If a change in the email or password occurs, a get request to the UserDataChangeURL with the following parameters is invoked.
Parameter | Description |
user_token | token identifying the customer (reserved / empty) |
email address identifying the user (mandatory) | |
new_email | new email address of the user (optional) |
old_pw_hash | old password hash of the user (optional but required for verification purposes if new new_pw_hash is specified) |
new_pw_hash | new password hash of the user (optional) |
pw_hash_type |
int identifying the password hash algorithm (required if old_pw_hash and/or new_pw_hash is specified)
|
signature | signature to validate the post as described below |
The signature used is calculated as SHA-1 hash (hexadecimal output) from the request parameters. The first parameter has to be your secret, followed by the parameters ordered alphabetically by their names. Optional arguments that are used (have value) must be contained in the signature calculation. Optional arguments that are not used must not be contained in the signature calculation.
It is mandatory to convert arguments values into UTF-8 before computing the signature.
Example:
signature = sha1_hex( secret + ":email=" + email + ":new_email=" + new_email + ":new_pw_hash=" + new_pw_hash + ":old_pw_hash=" + old_pw_hash + ":pw_hash_type=" + pw_hash_type)
Example calculation:
Value | Description |
Secret | BddJxtUBkDgFB9kj7Zwguxde4gAqha |
Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein! | |
new_email | Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein! |
new_pw_hash | a2a1e3f447524d73729d972db3f837c5:MD |
old_pw_hash | cc3469055de99a54451507fdf66a3a00:MD |
pw_hash_type | int identifying the password hash algorithm (required if old_pw_hash and/or new_pw_hash is specified) |
Signature calculation using the values above:
signature = sha1_hex(BddJxtUBkDgFB9kj7Zwguxde4gAqha:email=Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!:new_email=Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!:new_pw_hash=a2a1e3f447524d73729d972db3f837c5:MD:old_pw_hash=cc3469055de99a54451507fdf66a3a00:MD:pw_hash_type=4) => a043071d3db1d3bbacee04e1eaf07da0d3ab1d17
The request then is:
https://sample.update.com/update?email=Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!&new_email=Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!&new_pw_hash=a2a1e3f447524d73729d972db3f837c5:MD&old_pw_hash=cc3469055de99a54451507fdf66a3a00:MD&pw_hash_type=4&signature=a043071 d3db1d3bbacee04e1eaf07da0d3ab1d17