Add-on versioning

What is Versioning?

Versioning is created for the agency's needs to make changes to the public or development part of the add-on after its approval.

Versioning Process

Versioning is activated when the add-on is approved and someone from the users, or the agency itself, changes the information in the Addon Info section or the Add-on Development of the addon section.
Each part can be versioned independently.

Preview of Changes in Add-on Information:

• If you make changes to the customer-facing texts, a new "Preview" button will appear next to the "Detail" button. This preview will redirect you to the FrontEnd part of the Marketplace, where you can see the changes you have made. The "Detail" button will continue to display the last approved version of the article, which your customers see. Once the changes are approved, the preview button will disappear, and the changes will be transferred to the add-on article for customers to see.

If the Change is in the Development Part of the Add-on:

• Once the agency has completed its changes, it will properly test the add-on (in case of changes in the development part) and then send the changes for approval to Upgates using the "Save and Submit for Approval" button.
• Before submitting for approval, the agency will list all the changes made so that customers know what is new in the update. A form for the update text will pop up after clicking the "Save and Submit for Approval" button. The changes will then be reflected in the add-on article details (at the bottom).

Note: The values you enter will be reflected in the article details after the version is approved. Please ensure the texts are presented as you would write them to your customer.ozor!

Once the new version of the add-on is approved, all customers will receive a notification that a new version of your add-on has been created and that they need to switch to it. 

Note: After the new version of the add-on is approved, the add-on will exist in two versions. Version 1 will be active for customers who activated it before the approval of Version 2. Version 2 will be active for customers who switch to the new version or activate the add-on after the approval of Version 2. It is important to consider this and not transfer customers with Version 1 to new endpoints added in Version 2. Automatic control could temporarily suspend your add-on if it detects repeated requests to unauthorized endpoints. You can determine which version the client is using from the token attribute, which is always included in each Activation, Opening, and Update endpoint.

If you only change the URL endpoint (for Activation, Opening, Versioning, Uninstallation) or the intervals of already established API endpoints in the development part, the option to switch to the new version will not be triggered for customers. It will happen automatically. The customer "approves" the switch to the new version only if access to a part of the API that was not previously agreed upon is added/removed. For example, if you previously did not work with /categories but now require it, the customer must approve this. However, if you already use /categories and only change the frequency of use, the customer does not need to approve this.

Switching to the New Version

Every Upgates client has instructions in the help section on how to switch to the new version of the add-on. This information is also sent via email once the new version is approved by Upgates. More information on what the update looks like from the customer's perspective can be found in this article (CZ).

For you, as a developer, it is important to know that switching to the new version is done in the add-ons list by clicking the "Update Version" button.

Deactivating the Old Version

Once the new version of the add-on is approved, all customers will receive a notification that a new version of your add-on has been created and that they need to switch to it. They have 30 days to make the switch. If they do not switch to the new version within this period, their add-on will be deactivated.

How to Find the Version of an Add-on?

List of Add-ons:

1. Go to the Add-ons / My Add-ons section.
2. Find the relevant add-on.
3. In the row with the add-on, locate the Version column to find the current version of your add-on.

Add-on Details:

1. Go to the Add-ons / My Add-ons section.
2. Select the relevant add-on.
3. Next to the name of your add-on, you will see both the status and the version of your add-on.

Identification of the version used by the customer

Thanks to the version attribute, you can find out exactly which version of your add-on the customer is using and thus, for example, send the correct information to the iframe.
The version number always increases with a new version of the add-on. By approving it, it doesn't become version 1 again. Each version means moving up in the number series..

"version" => $version intiger

Documentation

Request body

{
"token": "",
"version": "",
"time": "",
"signature": "",
"signature_v2": ""
}
                                        

Response body

{
"error": false,
"message": ""
}
                                            

Signature specimen:

<?php
$data = implode(";", [
    "token" => "...",
    ]);
$signature = 'a0e0a3e7689bd4c80e4d6ffcccb05235b864e1d0';
$signaturePublicKey = file_get_contents("https://files.upgates.com/addons/signature/api.signature.pub.key");
$verify = openssl_verify($data, base64_decode($signature), $signaturePublicKey, OPENSSL_ALGO_SHA256);
            
        

<?php
$data = implode(";", [
    "token" => "...",
    "time" => "...",
    "signature_token" => "...",
    ]);
$signature = 'a0e0a3e7689bd4c80e4d6ffcccb05235b864e1d0';
$signaturePublicKey = file_get_contents("https://files.upgates.com/addons/signature/api.signature.pub.key");
$verify = openssl_verify($data, base64_decode($signature), $signaturePublicKey, OPENSSL_ALGO_SHA256);
            
        

Failed installation

• The add-on cannot be activated if:
  • Your answer is longer than 5 seconds.
  • Any response other than HTTP status code 200.
  • HTTP 200 response is not valid.

Answer (Validation)

• required attribut error
  • TRUE (bool) - Problem on the add-on side - installation would be fine, but the customer has to meet additional conditions before they can install the add-on.
  • FALSE (bool) - Everything went fine, the add-on is successfully installed.
• cURL supported content encoding
  • libcurl
  • deflate
  • gzip
  • br
  • zstd