WebsiteGitHubSlackLogin

5. Data Plugs

Data Plugs

In the PDA ecosystem, Data Plug is a minimal API-to-API web service with the primary purpose of fetching data from third party API and pushing it to the user's PDA. Due to the security considerations and limited scope of required functionality, each data plug is granted a write-only access to any particular PDA.

Fetch Data Plugs and Applications

HAT for iOS provides an API call for you to fetch all the available Data Plugs:

HATExternalAppsService.getExternalApps(
            userToken: userToken,
            userDomain: userDomain,
            completion: availablePlugsReceived,
            failCallBack: errorRetrievingDataPlugs)

As you may have noticed, the function name is getExternalApps. Applications and Data Plugs are not only represented by the same structure but they have the same API as well.

  • userToken is the user's token to authenticate with the PDA.

  • userDomain is the user's PDA address used to form the url to fetch the Data Plugs.

  • completion is a callback that is called when the request was successful. It has type of @escaping (([HATApplicationObject], String?) -> Void).

    The first parameter is an array of HATApplicationObject. This is the structure of Data Plugs and Applications. More on that in the next section.

    This array contains all the Data Plugs and Applications on the PDA. The second parameter is an optional String, the refreshed user token that the PDA returns.

  • failCallBack is a callback that is called when the request has failed. The type of the function is @escaping ((HATTableError) -> Void). HATTableError is a custom object describing the errors that have occurred during the querying of the tables in the database.

A successful response will have statusCode 200 and look like this:

  • application holds the most parts of the structure. It consists of the following 7 values:

  1. id in the application part of the JSON is the id of the Data Plug in the HAT.

    1. kind in the application part of the JSON has 4 values holding the various urls and the type of the Data Plug:

      1. url is the url of the Data Plug or Application to use in web

      2. iosUrl is the iTunes url of the Application in the App Store. It's optional and only there for Application type

      3. androidUrl is the Play Store url of the Application in the Play Store. It's optional and only there for Application type

      4. kind is the kind. As we mentioned earlier Data Plug and Application is represented by the same structure and use the same APIs

        • Therefore, the kind can be App or Data Plug. When for example you want only the Applications then simply you are going to filter the array based on the kind.

  2. info in the application part of the JSON has 12 values:

    1. version is the version number of the app in the HAT. This may be different from the version number of the Application in the App Store or Play Store

    2. updateNotes is essentially the release notes for the latest version. It is formed by the header, the title of the release notes, and the notes an array of String to easily show the notes as an unordered list.

    3. published indicates if the app is published or not. It can be that the app is not yet published, so it's not yet live, and it's testing, beta, app

    4. name is the official name of the app

    5. headline is the headline or subtitle of the app. It can be placed underneath the name for example, to provide more context for the app if needed.

    6. description allows you to describe your app better with a longer text. Also, it has support for different formats of text,text, markdown and html. markdown and html are optional.

    7. termsUrl is a URL of the terms and conditions. Users must be able to read them if they wish.

    8. dataUsePurpose is a text explaining why and how the app will use the data

    9. supportContact a support email. Users will use this email to contact you.

    10. rating is an optional object formed by score which describes the permissions and the data use using a letter-based scoring system. You can read more here.

    11. dataPreview is actually an array of SheFeed structures. This is used to preview items, if any, instead of making another network request to fetch those items. The array can be empty.

  3. graphics is a structure formed by 3 values:

    1. banner is the URL of the banner image

    2. logo is the URL of the app logo image

    3. screenshots is the URL of the app's screenshots used to showcase what this app offers.

      • All the above 3 values use the same structure. PDA images can be categorised as small, normal, large and xlarge.

      • Except normal all are optional values.

  4. developer consists of some basic info about the developer. This includes: id, name, url and country.

  5. permissions includes 3 values:

    1. rolesGranted which is an array of role and detail, optional, describing the roles granted in the Application.

    2. dataRetrieved which is a type of DataOfferRequiredDataDefinitionObjectV2. It describes the data that the Application will retrieve. optional.

      1. rolling describes if the data have a rolling start date

      2. bundle You can read more about it here

      3. startDate the start date of the bundle. optional

      4. endDate the end date of the bundle. optional

    3. dataRequired which is a type of HATExternalAppsDataRequiredObject. optional

  6. setup encapsulates all the urls that the Application needs in order to setup. The structure is the same as kind but the urls can be different

  7. status provides some info about the status of the application:

    1. compatibility – the last version that is compatible with the current one

    2. versionReleaseDate – the date, in ISO format, of the latest release

    3. kind – the kind of the release. It can be either Internal or External.

    4. recentDataCheckEndpoint –  a URL pointing on the most recent data point. optional

    5. statusUrl –  a URL to check the status of the Application or Data Plug. optional

    6. expectedStatus – the expected status number. optional

    7. dataPreviewEndpoint – a URL pointing to the actual data on the PDA to show them as a preview. optional

  • setup Boolean value indicating if this app has been setup successfully

  • enabled Boolean value indicating if this app has been enabled successfully

  • active Boolean value indicating if this app is currently active or not

  • needsUpdating Boolean value indicating if this app needs updating. An Application may need an update in case the terms

    have changed or a new version has been released.

A request that has failed will look like this:

  • error is the error that has occurred

  • message is a more descriptive message about the error that has occurred

Set up an Application

Setting up an application is similar to the login process. First you have to check the kind; is it App, or Data Plug. The 2 of them are different in how you set them up.

In the case of an App you first have to check if the app is already installed on the user's device. To do that you have to check with:

where appURL is the iosUrl from the Application -> setup. If user has the app installed, then you have to form a URL like this:

  • hatAddress is the (fully qualified domain) address of the PDA, e.g. postman.hubat.net

  • appID is the id of the application to setup.

  • appURL is the URL where the user should be sent to after completing authentication. In this case it is the iosURL.

  • fallback is the URL where the user should be sent to in case the authentication has failed. Optional. For an iOSapplication that would probably be: \(applicationName)://failed and has to be added in the info.plist file of the project in Xcode as a known URL.

As you may have noticed this is exactly the same URL as the login URL and there is a reason for this. The setup process goes through web. Just like during the login process, the user will be asked to insert their password before continuing to the next step. The next step is accepting the terms and conditions and giving the permissions the app requires to function. After that if everything goes smoothly, PDA will redirect back to the success redirect. The redirect url will now include a parameter which is the token for the particular app. iOS will ask the user if they want to launch the particular app. If the user selects "yes" then the app will be launched. If there is a problem, DA will redirect to the fallback url and you have to hide Safari and show a message that something went wrong.

If you don't know how to handle SFSafariViewController you can read more here.

If the user does not have the app installed, you first have to redirect them to the App Store in order for them to download the app. The URL that you have to use the url in Application -> kind. Again the only thing you have to do is open it using Safari. When the user has installed the app they may then tap again to set up the Application.

Set up Data Plug

Setting up a Data Plug is a lot simpler than setting up an Application. You just open the url in Application -> kind with safari and follow the instructions. Again, the user will first have to enter the password. After that each Data Plug has a different way of asking permissions and registering with the PDA.

State of the Application and Data Plug

Application and Data Plug can be in multiple states. Setup, failing, need updating, disabled. To respond in state changes you can use the following snippet:

  • connected is the case when the Application or Data Plug is enabled, active and it doesn't needsUpdating.

  • fetching is the case when the Application or Data Plug is enabled, active, it's an App and the mostRecentData is nil. This means that no data have been saved in the PDA yet.

  • needsUpdating is the case when the Application or Data Plug is marked as needsUpdating in the API response. This means the user has to go through the setup process again.

  • failing is the case when there is a problem in the Application or Data Plug. Setting up again might or might not help. In case this persists please do contact us.

  • notConnected is the case when the Application or Data Plug has never been set up before.

Disable Data Plug or Application

You can also disable a Data Plug or an Application. To do that you can call the next function:

  • appID is the id, in Application structure, of the Application or Data Plug

  • userDomain is the user's PDA address used to form the url to disable the Data Plug or Application

  • userToken is the user's token used to authenticate with the PDA

  • completion is a callback function that is called when the request is successful with a type of @escaping @escaping ((HATApplicationObject, String?) -> Void). The first parameter is the disabled HATApplicationObject. The second parameter is an optional String, the refreshed user token that the PDA returns.

  • failCallBack is a callback that is called when the request has failed. The type of the function is @escaping ((HATTableError) -> Void). HATTableError is a custom object describing the errors that have occurred during the querying of the tables in the database.

A successful response will have statusCode 201 and look like this:

If you are not familiar with the structure you can read more here.

A request that has failed will look like this:

  • error is the error that has occurred

  • message is a more descriptive message about the error that has occurred

Last updated

Was this helpful?