Tutorial: how to publish a Java Card application


This tutorial is the continuation of the Java Card tutorial. In this tutorial, you will learn to publish the cardlet created there, so that anybody owning a Fidesmo Card will be able to install it using an Android phone.

What you need for this tutorial

This tutorial does not require anything other than the list in the previous tutorial.

Step by step

Configure the application in the Fidesmo Developer Portal

If you have not done it yet, sign in to the Fidesmo Developer Portal and go to the Applications page. From the list of applications, select the one you defined in the previous tutorial.

Click the “Edit <application name>” link on the top right of the page, just under the menu. Fill in the “Name” field. You can leave the rest of the fields empty, or with the default values. Click the “Update Application” button.

Now you can review the changes and upload an SVG image file: the logo that represents your company. It will be also displayed to the user during the installation phase. If you did not upload a logo, a default image will be shown. You can use the form in your application page (next to the "Logo" label) to browse your filesystem, select a logo and upload it.

Upload the cardlet

As this continues this other tutorial, we assume that you have made all the preparations, downloaded FDSM and built the cardlet. Now we are going to upload the cardlet’s CAP file to the Fidesmo server, associating it to the application you just configured above.

You just need one command:

cmd> fdsm -upload <applet.cap> -app-id <your_app_id> -app-key <your_app_key>

In case you are not using the Fidesmo SDK to build the cardlet, you can also upload a CAP file directly using one of our API operations. Here we are calling it using CURL:

cmd> curl https://api.fidesmo.com/executableLoadFiles -H 'app_id: <app_id>' -H 'app_key: <app_key>' -H 'content-type: application/octet-stream' --data-binary @path/to/elf.cap

Don't forget of course to replace the placeholders <app_id>, <app_key> and path/to/elf.cap with the values corresponding to your application.

It is very easy to verify that the cardlet was built and uploaded successfully. Go to the API page, scroll down, click on the API operation “List executable load files ready for installation on card”, fill-in the app_id and app_key fields and click the Try it out! button.

The response will be displayed below the form. The Response Body will contain a list of all the CAP files associated to your application. In our example, using the same Application ID as in the previous tutorial, we can see that it is there:

Response Body
    "appId": "C8739B19",
    "elfAid": "A00000061700C8739B19",
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "javaCardVersion": "3.0.1",
    "locationType": "cap",
    "metadata": {}

Write a Service Recipe

Now the CAP file is available to be installed on any Fidesmo Card. We could set up a server that implements the Service Delivery process, installing it using the API operation “Install application to card”; but, since we don’t really need to set up a server that interacts with the cardlet, we can use a much easier method: write a service recipe and upload it to the Fidesmo Server.
Uploading a service recipe has the added benefit that the service description will appear in the Fidesmo App’s application listing, making it much easier for end users to discover and install it.

Below is the service recipe we will use. It is composed of three parts:

  • A service description: the text that will be shown to the user during the installation process.
  • Actions: list of operations to be performed, all belonging to the Fidesmo API. In our case, we just need to send one, the “Install application to card” mentioned above, including the information mentioned in the API documentation. In this case, it is the set of AIDs needed to register the cardlet on the card. If the service recipe does not have any actions, the service will still be visible in the Fidesmo App store, but the backend server of the application's provider will be called (the "Service Delivery URL" in Applications page.)
  • Success and failure messages: The messages displayed to the user if the service delivery finishes successfully or fails.

Using the AIDs derived from the application used throughout this example (AppID = C8739B19), this is the service recipe:

  "description": {
                 "title": "Install the Hello Fidesmo cardlet"
  "actions": [
               "endpoint": "/ccm/install",
               "content": {
                           "executableLoadFile": "A00000061700C8739B19",
                           "executableModule": "A00000061700C8739B1901",
                           "application": "A00000061700C8739B1901"
  "successMessage": "Cardlet successfully installed",
  "failureMessage": "Cardlet installation failed"

Publish the Service Recipe

To make our cardlet available to the entire Fidesmo ecosystem, we will use other of the operations in the Fidesmo API: “Upload a service recipe”.
One of the parameters we need to define is the serviceID, because an application can be composed of several services. Let’s use HelloFidesmo.
Although we can use the form that opens up when clicking the operation in the Fidesmo API description, let’s use CURL so we can print the entire command here:

cmd> curl -v -H "app_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -X PUT "https://api.fidesmo.com/apps/c8739b19/services/HelloFidesmo/recipe" -d '{ "description": { "title": "Install the Hello Fidesmo cardlet" }, "actions": [ { "endpoint": "/ccm/install", "content": { "executableLoadFile": "A00000061700C8739B19", "executableModule": "A00000061700C8739B1901", "application": "A00000061700C8739B1901" } } ], "successMessage": "Cardlet successfully installed", "failureMessage":"Cardlet installation failed" }'

Don't forget to replace the fake app_key with the one assigned to your application, and the app_id sent as part of the URL.

If you want to make it available through the Fidesmo App Store, you will need to follow these guidelines.

Test it!

The previous CURL command returned HTTP 200 OK, but let’s not be satisfied with it: are we sure that our cardlet can be installed by anyone having a Fidesmo Card?
Let’s see:

  • Open the Fidesmo App in an Android phone. The “Cardapps” store will open and display a list of publicly available applications.
  • Scroll down until you find an entry showing your logo beside the name you chose for your organization when signing up into Fidesmo Developer Portal.
  • Press it!
  • You will see the list of services provided by your application: at least one, named with the title used in the description field of the service recipe.
  • Press it!
  • Follow the instructions appearing on the phone screen… Congratulations! The cardlet is now installed on your Fidesmo Card!

An alternative method, available even if you have not published your service, is to use the "Manual service order” in the Android app. You will need to enter the appId and serviceID used above.

If you still want more proof, you can verify that the cardlet has really been installed on the card by following the last part of the Java Card tutorial.