Looking for the new OutSystems Now? Click here!
Building your own app
Building native applications is not easy but we have worked hard to make your life simple. OutSystems Now is a great way of having your  applications running on mobile devices as easy as building any other OutSystems application. You can still extend your applications with access to the native device features with plugins provided by us.
OutSystems Now is a great application and we did not want to leave anyone out, so we've decided to share its source code with all of you. You can build your own version of OutSystems Now and make your applications available in Apple, Google and Windows stores (your application must be compliant with store guidelines).
What can you do with the open source code?
The OutSystems Now open source code allows you to build your own version without starting from scratch. Customizing the source code allows you to do many great things:
Rename the application. You can give it your own company name or any other name you decide (as long as Apple, Google and Windows stores approve it);
- Because you own the application, use the Push Message services to reach all your users. Use also third party services such as Pushwoosh or UrbanAirship and avoid much complexity when sending push notifications.
Steps for building your own custom app
1. You can use a GitHub client (Windows or Mac) to get the source code from the GitHub repositories. Either clone (or fork) the repository (if you have the GitHub client) or just download it as a zip file to have a local copy. As with any open source project, you may eventually want to merge your current code with the latest version, as new versions are likely to be released while you are building your own.
2. Setup your development environment(s)
 iOS
 Android
 Windows
Download XCode to your mac and open the OutSystems.xcodeproj project file (in the folder platforms\ios).  An iOS developer account will be required for developing your application and submitting it to the store. 
Download and install Android Studio in your computer. After installing it, open the Android SDK Manager and make sure that you have installed the following packages:
Android SDK Tools 25.1.6
Android SDK Platform-tools 23.1
Android SDK Build-tools 23.0.3
Android SDK Build-tools 20
Android 4.4W.2 SDK Platform
Android 4.4.2 SDK Platform 
Android Support Repository
Android Support Library
Google Repository
Google USB Driver
Intel x86 Emulator Accelerator 
In Android Studio, open your project using the Open an existing Android Studio project option and choose the outsystems-app-android folder. 
If you also wish to submit the application to Google Play, you will also need a Google Play Developer
Download and install Microsoft Visual Studio in your computer and open the CordovaApp.sln solution file (in the folder platforms\windows).  A Windows Store Developer account will be required for developing your application and submitting it to the store. 
3. Open the GitHub source code in your development environment and you are ready to start building your own version of the application. To learn more about the XCode development environment checkout the Xcode Overview. If you wish to start with the Android version, you also have a complete list for tutorials available online in the Android Training documentation. Otherwise, you can learn more about the  development of Windows Universal Apps.
 iOS
 Android
 Windows
Creating your own application means that you need to create a new application Bundlie Identifier. Select the OutSystems project and then the OutSystems target (the other ones are solely for internal development). You can find the Application Identifier in the Identity Settings, under the General tab. You will not be able to use a Bundle Identifier already in use by another application, therefore it's probable you find inverted addresses like com.outsystems.appname.
To change the application name on the home screen, still under the same target, select the Build Settings tab and scroll down to the Packaging section. There you will find a setting for Product Name. Double click on the value and update it with the new name.
In your XCode project you can find all images related with the application logo and splash screen under OutSystems > Resources > Images.xcassets. You will need several different image sizes due to the multitude of devices with or without retina displays. For further details, check the iOS Human Interface Guidelines online.
You will also want to customize the OutSystems logo image that appears on the first screen, where the user types the environment address. You can find that image (logo_iphone5.png) under the images folder (OutSystems > Resources > images). To keep it simple we recommend that you should replace it with an image with the same dimensions (530x80), with a transparent background. If you need help creating icons and splash screen, there are several websites, such as TiCons, that generate all the necessary files.
To push notifications we suggest that you use a third-party service sush as PushWoosh or UrbanShip (paid services).  These services simplify the whole process of pushing notifications and, better yet, they provide a single way of doing it for iOS, Android and Windows. No need to develop custom push mechanisms for each vendor. There are several other companies offering the same services and you can work with any of those if you wish. Most of them are paid services, so a subscription fee may be necessary.
To learn more about Push Notifications, check out the online documention About Local Notifications and Push Notifications. For iOS, You will be required to create a provisioning profile that supports push notifications.
To enable the deep linking feature on your own application you need to change the Application Protocol. Select the OutSystems project and then the OutSystems target (the other ones are solely for internal development). You can find the Application Protocol in the URL Types settings under the Info tab. Change the Identifier with yours and choose the new URL Schema for your application. Also, you need to change the URL Identifier and the URL Schema on the Additional Url Type Properties settings.
In Android you will be required to change the package identifier, because it is the unique identifier for each Android App. You will not be able to upload your application o the store if there is already another application using the same identifier. To change the package identifier, follow the next instructions:
- In the Project pane, click on the gear icon and uncheck the Flatten Packages and Compact Empty Middle Packages options
- Individually select each directory you want to rename, and:
- Right-click it
- Select Refactor
- Click on Rename
- In the Pop-up dialog, click on Rename Package instead of Rename Directory
- Enter the new name and hit Refactor
- Allow a minute to let Android Studio update all changes
- Now open your ApplicationManifest.xml file, and change the package name to the new name
Note: We recommend you to search and replace the old name with the new name. This will avoid conflicts with the original OutSystems Now app when you install your custom app on a device.
- Finally, open your build.gradle file (Module: android) and update the applicationId to your new Package Name and Sync Gradle
The current application name can be found along with multiple other configurations in the strings.xml file, which you can find under the OutSystems\res\values folder in the Package Explorer. Double click to open the file and choose the strings.xml view (last tab below the file content view), which allows you to view and edit the raw XML content. There you will find an entry for app_name, which you can change to your application name.
Under the Package Explorer, you can find the application logo (icon.png) inside the following folders: drawable-mdpi, drawable-hdpi and drawable-xhdpi. You can find all these folders under the OutSystems > res folder. Replace that files with the logo image that you wish to use, respecting the image dimensions.
As for the splash screen, due to the vast list of Android devices and screen sizes out there, we decided to use a different approach. Under the OutSystems > res folder you will find several bg_red.jpg files used for the different splash screens. These files are used as background images. As for the foreground logo, you can also find the logo.png file, which you should update to your own brand file. The logo.png file is available inside the following folders: drawable-ldpi, drawable-mdpi, drawable-hdpi, drawable-xhdpi and drawable-sw600dp. If you need help creating application icons and splash screen, there are several websites, such as TiCons, that generate all the necessary files needed.
To push notifications we suggest that you use a third party service such as PushWoosh or UrbanShip (paid services).  These services simplify the whole process of pushing notifications and, better yet, they provide a single way of doing it for iOS, Android and Windows. No need to develop custom push mechanisms for each vendor. There are several other companies offering the same services and you can work with any of those if you wish. Most of them are paid services, so a subscription fee may be necessary.
To learn more about Push Notifications, check out the online documention Google Cloud Messaging for Android.
To enable the deep linking feature on your own application you need to change the Application Protocol. In the Project panel, open your ApplicationManifest.xml file under the Android project, and search for the android:scheme. Replace the current application protocol with your own protocol. We recommend you to use lowercase.
Submiting your own Windows App to the Windows Store means that you need to reserve your app name first. This action will ensure that no one else uses the name. Learn how you can reserve your app name. After reserving you app name you need to change the display name. To change the display name of your app, follow the next instructions:
- In the Solution Explorer, double-click on the appxmanifest file of CordovaApp.Phone project
- Select the Application tab
- Change the Display name
- Repeat this steps for the CordovaApp.Windows project
Now that you have changed the display name of your app, you need to associate your app with the app name that you initially reserved for Windows Store submission. To associate your app with the Store, follow the next instructions:
- In the Solution Explorer, right-click on the CordovaApp.Phone project 
- Select Store
- Click on Associate App with the Store 
- Sign in to the Windows Phone Store
- Select the App Name for your app
- Associate your app
- Repeat this steps for the CordovaApp.Windows project
In your Visual Studio project you can find all images related with the application logo and splash screen on the Visual Assets tab of the appxmanifest file of your CordovaApp projects. You will need several different image sizes due to the multitude of devices. You can find that images under the images folder (platforms > windows > images).
You will also want to customize the OutSystems logo image that appears on the first screen, where the user types the environment address. You can find that image (logo_original.png) under the img folder (platforms > windows > www > img). To keep it simple we recommend that you should replace it with an image with the same dimensions (530x80), with a transparent background. If you need help creating icons and splash screen, there are several websites, such as TiCons, that generate all the necessary files.
To push notifications we suggest that you use a third-party service sush as PushWoosh or UrbanShip (paid services).  These services simplify the whole process of pushing notifications and, better yet, they provide a single way of doing it for iOS, Android and Windows. No need to develop custom push mechanisms for each vendor. There are several other companies offering the same services and you can work with any of those if you wish. Most of them are paid services, so a subscription fee may be necessary.
To learn more about Push Notifications, check out the online documention Push notifications for Windows Phone
To enable the deep linking feature on your own application you need to change the Application Protocol. Open the AppManifest file of the Windows Phone project and select the Declarations tab. Find the Protocol declaration and change both the Display Name and Name. Repeat this steps for the AppManifest file of the Windows 8.1 project.
4. Now that you have your own version of the OutSystems Now application it is time to distribute it. Learn how you can distribute your app on the Apple Store or, if you want to publish the Android version, checkout the Get Started with Publishing guide. Otherwise, you can learn how to publish your app on Windows Store.
5. Congrats! You now have your application being distributed to all your users in the three major mobile stores.
Steps for managing Cordova Plugins in your own custom app
OutSystems Now is shipped with a small set of Cordova Plugins listed on the Features page. In this section, we will help you managing Cordova Plugins in your custom app.
Cordova command-line tool
The management of Cordova Plugins is done through Cordova command-line tool, also known as CLI. To install the Cordova command-line tool, follow these steps: 
1. Download and install Node.js on your computer. Following installation, you should be able to invoke node and npm on your command line.
2. Download and install a git client on your computer. Following installation, you should be able to invoke git on your command line.
3. Download and install Cordova module using npm utility of Node.js by running the following command on your command line:
 npm install -g cordova
 To learn more about the Command-Line Interface, check the documentation.
Cordova Plugin management
After installing Cordova command-line tool, open your command line, go to your application folder and start managing Cordova Plugins in your own app using CLI.
If you are working on an Android version, your application folder is OutSystemsNow-Android > outsystems-app-android >  OutSystems.
If you are working on an iOS version, your application folder is OutSystemsNow-iOS.
If you are working on a Windows version, your application folder is OutSystemsNow-Windows.
To list all the plugins installed on your own app, run the following command on your command line: 
 cordova plugins list
A list of plugins, including additional third-party plugins provided by the community, can be found in the registry at plugins.cordova.io. Also, you can search for plugins using CLI by running the following command on your command line: 
 cordova plugins search <keywords>
To install a plugin using CLI, you need to specify the repository for the plugin code by running the following command on your command line: 
 cordova plugins add <plugin-repository>
You can install a specific version of the plugin by running the followind command on your command line:
 cordova plugins add <plugin-repository>@<version>
Also, you can install a plugin from another git repository by running the followind command on your command line:
 cordova plugins add <plugin-URL>
To remove a plugin from your own app using CLI, you need to specify the plugin identifier that appears in the listing by running the following command on your command line:
 cordova plugins remove <plugin-identifier>
 To learn more about Cordova Plugins development, check the documentation.
Steps for adding Mobile Feedback in your own custom app
The latest version of OutSystems Now available on GitHub was released with the Mobile Feedback feature included. However, if you have a custom app based on an older version of OutSystems Now, the following instructions will help you to add the Mobile Feedback to your app.
 iOS
 Android
 Windows
a. Download the source code of OutSystems Now for iOS
Get the latest version of OutSystems Now for iOS from GitHub.
b. Copy Mobile Feedback Framework file into your project folder
i. After downloading the source code, go to the OutSystems Now project folder and search for the Frameworks folder 
ii. Copy the OutSystemsMobileECT.bundle and OutSystemsMobileECT.framework files inside the Frameworks folder
iii. Create a folder for the framework inside your project folder
iv. Paste the OutSystemsMobileECT.bundle and OutSystemsMobileECT.framework files into the new folder of your project 
c. Add Mobile Feedback Framework to your project
i. Open your project in Xcode 
ii. In Project Navigator, right click on the Frameworks group
iii. Select Add Files to <Your Project Name> option
iv. Select the OutSystemsMobileECT.bundle and OutSystemsMobileECT.framework files from your project folder 
a. Add the Mobile Feedback view to your Web Application View Controller
i. Open your storyboard file for iPad
ii. Select your Web Application View Contoller
iii. Add a new View inside the ApplicationView and below the LoadingView and call it ECTView
iv. Repeat these steps on your storyboard file for iPhone
b. Add the Mobile Feedback to your Web Application View Controller class
i. Open your storyboard file for iPad
ii. Select your Web Application View Contoller
iii. Create a Referencing Outlet for the ECTView to your Web Application View Controller class file
iv. Repeat these steps on your storyboard file for iPhone 
v. Open your Web Application View Controller header file
vi. Import OutSystemsMobileECT/OutSystemsMobileECT.h
vii. Add a property for the Mobile Feedback controller
@property (strong,nonatomic) OSMobileECTController *mobileECTController;
viii. Open you Web Application View Controller class file
ix. Initialize the Mobile Feedback controller
The initialization of the Mobile Feedback controller must be performed at the viewDidLoad method.
self.mobileECTController = [[OSMobileECTController alloc] initWithSuperView:self.mobileECTView andWebView:self.applicationBrowser.webView forHostname:self.infrastructure.hostname ];

[self.mobileECTController addOnExitEvent:self withSelector:@selector(onExitECT)];

[self.mobileECTController prepareForViewDidLoad];
x. Implement the missing method 
onExitECT
This method will be fired when the user presses the Close button of the Mobile Feedback view.
You can add here some logic for your application.
xi. Prepare Mobile Feedback to appear 
The preparation must be performed at the viewWillAppear method.
if(!self.mobileECTController){
   self.mobileECTController = [[OSMobileECTController alloc] initWithSuperView:self.mobileECTView
   andWebView:self.applicationBrowser.webView forHostname:self.infrastructure.hostname ];

   [self.mobileECTController prepareForViewDidLoad];
}

[self.mobileECTController prepareForViewWillAppear];
xii. Release the controller when the Web Application View Controller disappear
The controller must be released at the viewWillDisappear method.
[self.mobileECTController preparedForUnload];
self.mobileECTController = nil; 
a. Add a feedback button to the Toolbar of your Web Application View Controller
i. Open your storyboard file for iPad
ii. Add a button to invoke Mobile Feedback and call it ECTButton
iii. Create a Referencing Outlet for the ECTButton to your Web Application View Controller class file
iv. Repeat these steps on your storyboard file for iPhone
b. Add a Sent Action for the new button
i. Open your storyboard file for iPad
ii. Create a Sent Action for the ECTButton to your Web Application View Controller class file
iii. Repeat these steps on your storyboard file for iPhone
iv. Invoke the Mobile Feedback controller to open the Mobile Feedback view.
[self.mobileECTController skipHelper:skipHelper];
The skipHelper is a flag to show or skip the helper view when the Mobile Feedback view is displayed.
[self.mobileECTController openECTView];
c. Check if the App Feedback feature is available on your OutSystems Application
i. Go to your Web Application View Controller class file
ii. Override the webViewDidFinishLoad method
iii. Invoke the Mobile Feedback controller to get the App Feedback API
[self.mobileECTController isECTFeatureAvailable];
a. Download the source code of OutSystems Now for Android
Get the latest version of OutSystems Now for Android from GitHub.
b. Copy Mobile Feedback Framework file into your project folder
i. After downloading the source code, go to the OutSystems Now project folder and search for the MobileECT folder 
ii. Copy the MobileECT.aar file inside the MobileECT folder
iii. Create a folder for the framework inside your project folder
iv. Paste the MobileECT.arr into the new folder of your project 
c. Add Mobile Feedback Framework to your project
i. Open your project in Android Studio
ii. Create a new Module on your project
iii. Select the Import JAR or ARR Package option
iv. Select the MobileECT.arr file from your project folder
iv. Enter a name for the module you are creating and press Finish
d. Add a dependency of your application module to the Mobile Feedback Framework module
i. In Android Studio, right click on your application module
ii. Click on Open Module Settings
iii. Open the Dependencies tab
iv. Add a new Module Dependency to the created module
a. Add the Mobile Feedback view to your Web Application Activity view
i. Open your Web Application Activity layout file
ii. Group all the activity elements in an one main layout group
iii. Add a new layout group below the main group and call it ectViewGroup
b. Add the Mobile Feedback to your Web Application Activity class
i. Open your Web Application Activity java file
ii. Add a new field to your Activity class for the Mobile Feedback controller
private MobileECTController mobileECTController;
iii. Add the Mobile Feedback Container interface to the implementations of your Activity class
Your class will implement OSECTContainerListener interface
iv. Implement the missing methods of the OSECTContainerListener interface 
onSendFeedbackClickListener
This method will be fired when the user presses the Send button of the Mobile Feedback view.
You need to invoke the Mobile Feedback controller to send the user's feedback.
onCloseECTClickListener
This method will be fired when the user presses the Close button of the Mobile Feedback view.
You need to invoke the Mobile Feedback controller to close the Mobile Feedback view. 
onSendFeedbackClickListener
This method will be fired when the user close the Mobile Feedback Helper for the first time.
onShowECTFeatureListener
This method will be fired when the Mobile Feedback controller checks if the App Feedback feature is available on your OutSystems Application.
This method will allow you to show or hide a button for the Mobile Feedback on your custom app.
 
v. Initialize the Mobile Feedback controller
The initialization of the Mobile Feedback controller must be performed at the onCreate event.
mobileECTController = new MobileECTController(this, mainViewGroup, ectViewGroup, cordovaWebView, applicationHostname, skipHelper); 
The skipHelper is a flag to show or skip the helper view when the Mobile Feedback view is displayed.
a. Add a feedback button to the Toolbar of your Web Application Activity view
i. Open your Toolbar Web Application layout file
ii. Add a button to invoke Mobile Feedback and call it button_ect
b. Add a click listener for the new button
i. Open your Web Application Activity java file
ii. Implement the click listener for the button
iii. Invoke the Mobile Feedback controller to open the Mobile Feedback view.
mobileECTController.openECTView();
c. Check if the App Feedback feature is available on your OutSystems Application
i. Go to your Cordova Web Client class
ii. Override the onPageFinished method
ii. Invoke the Mobile Feedback controller to get the App Feedback API
mobileECTController.getECTAPIInfo();
 The Mobile Feedback feature is currently not available for the Windows platform.
Click here to see your activities