Onymos Raises $12M Series A: Learn why

onymos-logo
datastore icon

Quickstart Guide: DataStore Component

DataStore Component

Select a framework to get started.

Get started

Using Ionic or Cordova? Get the DataStore component working in your app in four easy steps.

  1. Download the component
  2. Add it to your environment
  3. Using DataStore
  4. Troubleshoot

1. Download the Onymos DataStore component

Sign up! We’ll send you a link to your component, set up your Onymos Cloud Account, and generate your Onymos license credentials. In the meantime, you can get familiar with our API Documentation and developer resources, or join a whole community of developers building apps with Onymos on Reddit!

2. Add it to your environment

Add your components to a folder in your app’s root (e.g., onymos_components).

Add the Onymos Initialize component to your environment.

$ ionic cordova plugin add onymos_components/onymos-component-initialize

Then we can add the Onymos DataStore component.

$ ionic cordova plugin add onymos_components/onymos-component-util

Then update the widget inside your config.xml with the Onymos Widget ID you receive after you create an Onymos Cloud Account.

3. Using DataStore

You don’t need to waste time configuring, securing, and hosting your own database anymore. We’ll do it all for you. Then use the Onymos DataStore component’s utility functions to send and receive all of the data your app needs. Take 200 MB of storage to get started—it’s on us.

Before we use DataStore, let’s make sure we have everything we need to configure your onymosConnectObject. The onymosConnectObject requires the appropriate Onymos license credentials: your Customer ID (also called an Onymos ID) and your Onymos Auth Token. You’ll need these credentials to use this (or any) component in your app. To generate your Onymos license credentials, create an Onymos Cloud Account.

NOTE: Your Onymos Auth Token will work with any number of apps and components. Onymos has a developer—and project—friendly pricing model. You can use any or all of our components in an app at no cost until it is installed on 100 or more devices. This is ideal for iterating your MVP (see detailed pricing here).

DataStore component settings
We make data storage easy with Onymos Hosting, but we offer you the framework to integrate Onymos components with your own cloud storage too. You’ll need to configure the onymosConnectObject, and in addition to your Customer ID and Onymos Auth Token, you’ll need to add values for optional properties. You can reach out to customersuccess@onymos.com to learn more.

{
  // Your AWS access and secret keys are provided when you use Onymos Hosting.
  awsAccessKey : 'Your AWS access key.', 
  awsSecretKey : 'Your AWS secret key.',
  awsSessionToken : 'Your AWS session token.', 
  // If you're using your own AWS hosting, provide the bucket for your data-store.
  // AWS support is only available for buckets created in the 'US Standard' region.
  // This isn't required when you're using Onymos Hosting.
  awsBucketFolder: 'Your folder in AWS.' 
}

All set? Let’s go inside your Ionic app’s app.component.ts file and initialize DataStore.

import { Component } from '@angular/core';
import { Platform } from '@ionic/angular';
    
    declare var OnymosInitialize: any;
    declare var OnymosUtil: any;
    
    @Component({
      selector: 'app-root',
      templateUrl: 'app.component.html',
      styleUrls: ['app.component.scss'],
    })
    export class AppComponent {
      constructor(
        private platform: Platform
      ) {
            this.initializeApp();
        }
      
     initializeApp(){
        this.platform.ready().then(() => {
    
          const OnymosConnectObject={
            customerId : 'Your customerId goes here', 
            onymosAuthToken : 'Your onymosAuthToken goes here',  
            envType: 'PRD'
            }
    
          OnymosInitialize.initialize(
            OnymosConnectObject,
          
            function onymosInitializeSuccess(status){
              console.log("Onymos initialized Successfully.", status)
            },
    
            function onymosInitializeFailure(error){
              console.log("Onymos failed to initialize.", error)
            })
        })
      }
    }
    

Great! If we configured your onymosConnectObject correctly, onymosInitializeSuccess() should print its message to the console. Now we’re ready to use DataStore.

Let’s create a function in the app.component.ts file so that users can select files from their devices to upload.

selectFile(){
  OnymosUtil.selectFile(
    callId,

    function fileSelectionSuccess(fileObj){
        fileObj = {
          fileName: 'The file name.',
          fileSize: 'The file size in megabytes.',
          fileType: 'The type of file selected.',
          fileURI: 'The local file path.'
        }
        console.log(fileObj)
    },

    function fileSelectionFailure(error){
      // Common errors  
      // User cancelled the selection process
      // User has not given permissions to the app to access Files
      console.log(error)
    })
}

CallId is a string used to identify each call to the selectFile() method. We can just use ‘1’ in most cases. On success, the fileSelectionSuccess() callback will return the fileObj, containing data about the file the user selected.

Inside of our callback, we could store some of the fileObj properties in an accessible variable so we can display them to users. Let’s try that!

  export class AppComponent {
    
    file: any={
        fileName: ''
        fileType: ''
    }

    constructor(

    [...]

    selectFile(){
        OnymosUtil.selectFile(
          '1',
      
          function fileSelectionSuccess(fileObj){
            this.file.fileName=fileObj.fileName
            this.file.fileType=fileObj.fileType
          },
      
          function fileSelectionFailure(error){
            console.log(error)
          })

From here, we can move to the app.component.html file to write the front-end code that calls the selectFile() function.

<div (click)="selectFile()">
  <h3>Select a File</h3>
</div>
<div>
  <p>{{file.fileName}}</p>
  <p>{{file.fileType}}</p>
</div>

Back in the app.component.ts file, we can write the function that actually uploads a user’s selected file to your database.

uploadFile(){
  OnymosUtil.uploadFile(
    callId,
    path,

    function uploadFileSuccess (statusMessage) {
      console.log(statusMessage);
    }, 

    function uploadFileFailure (error) {
      console.log(error);
    },

    options);
}

Your callId for the file being uploaded should be the same string used to identify that file when it was selected. The path is where you want to save the file. You can also customize an options object for even more control. You can see what all of your options are by checking out the DataStore API documentation.

What might the uploadFile() method look like when it’s configured?

uploadFile(){
    OnymosUtil.uploadFile(
      '1',
      https://s3.amazonaws...example-path,
  
      function uploadFileSuccess (statusMessage) {
        console.log(statusMessage);
      }, 
  
      function uploadFileFailure (error) {
        console.log(error);
      },
  
      {
        uploadSizeLimit: 15
      });
  }

We can add the finishing touches to our front-end code.

<div (click)="selectFile()">
  <h3>Select a File</h3>
</div>
<div (click)="uploadFile()">
  <img src="https://img.icons8.com/metro/52/000000/upload-to-cloud.png" alt="An upload icon" />
  <p>{{file.fileName}}</p>
  <p>{{file.fileType}}</p>
</div>

Now, your app lets users select files from their own devices to upload to your database! Think about making it a more user-friendly experience by adding the cancelSelectFile() and stopUploadFile() methods.

4. Troubleshooting

How do I squash this bug? Is Ionic supposed to do that? Why is this iOS build failing?

Let’s figure it out—join the Onymos community on Reddit! More of a loner? You can email us directly at customersuccess@onymos.com.

Dig into our API documentation

Developer support

Got questions? Our support team is here to help.

Think differently about app development

Download our free white paper today to learn how Onymos Features can maximize the value of your developer resources — and shave days or weeks off your development timeline.

Get your free white paper