Getting Started

This section guides how to install XStore from developement tool installation to system integration. It's recommend that you completed the system integration in this section to make sure the software is installed correctly before adding any customizations or extra codes to the project.

1. Development Environment Installation

a. Installing Xamarin

Choose an Operating System where you are installing Xamarin:

Mac OS:

Refer to this Step-by-step instructions.

Or below Video instructions:

Windows:

Refer to this Step-by-step instructions.

Or below Video instructions:

b. Build your first Xamarin.Forms App

This step describes how to create a new Example Xamarin Forms project, build and run the app.

note

Please note that this optional step just to make sure that environment is setup correctly. If you're expericenced in Xamarin then can skip this step.

  1. Open Visual Studio and select Create new project
  2. Search for "Xamarin" or choose Mobile from the Project type menu. Select the Mobile App (Xamarin.Forms) project type
  3. Choose a project name – for example "AwesomeApp"
  4. Click on the Blank project type and ensure Android and iOS are selected
  5. Wait until the NuGet packages are restored (a "Restore completed" message will appear in the status bar).
  6. New Visual Studio 2019 installations won't have an Android emulator configured. Click the dropdown arrow on the Debug button and choose Create Android Emulator to launch the emulator creation screen.
  7. In the emulator creation screen, use the default settings and click the Create button
  8. Creating an emulator will return you to the Device Manager window. Click the Start button to launch the new emulator.
  9. Visual Studio 2019 should now show the name of the new emulator on the Debug button
  10. Click the Debug button to build and deploy the application to the Android emulator.

Congratulation!! Your machine environment is ready, let get started to install XStore project.

Video instruction:


2. Run XStore with default demo website

This step show how to build and run the app with our WooCommerce demo website, it's expected that you can run the app as what you have seen in our Demo.

Step by step:

  1. After download and unzip the xstore-source.zip package, use Visual Studio to open the solution .sln under xstore-source folder.
  2. Wait until all packages restored, click Build > Rebuild Solution
  3. Click the Debug button to build and deploy the application to the Android emulator

Video guide:

note

If you got any errors in this section, please see the Common Issues section to find the error information and tip to solve it. In case you couldn't find solution, feel free to contact us for further support.


3. Integrate XStore with WooCommerce website

a. WooCommerce Website Setup

important

This section describes how to setup Wordpress website with WooCommerce and all required plugins. It's important that you follow the instruction to make sure the website is setup properly.

For your quickly setup, we included Pre-config website in the downloaded package. You can install this pre-config website to your local or live Wordpress hosting. See Quick Installation section for installation using Pre-config website.

If you want to setup new Wordpress site or use your existing Wordpress website, please go to section New or Existing Wordpress Setup.

I. Quick Installation

Find the preconfig website in your downloaded package, you can install this website to either localhost or live hosting.

Video guide how to install Wordpress website on localhost:

Windows:

Mac OS:


Video guide setup Wordpress on live hosting:

II. New or Existing Wordpress Setup

Following steps show installation on a fresh Wordpress website. This guide is based on our sample site at http://coffeestore.tlssoftwarevn.com

Step 1: Setup Rest API

The default Woocommerce supports the Rest API, but we need following steps to enable the API:

  • Requirements:

Custom permalinks must be enabled at: Settings > Permalinks. Default permalinks will not work.

alt text

Membership registration: Enable the option Anyone can register.

alt text

  • Enable REST API:

To enable the REST API for WooCommerce, go to WooCommerce > Settings > Advanced >Legacy API and tick the Enable REST API checkbox.

alt text

  • Generate API keys:

The WooCommerce REST API uses authenticated-key to control API access. These keys are linked to WordPress users on your website.

To create or manage keys for a specific WordPress user:

  1. Go to: WooCommerce > Settings > Advanced > REST API.
  2. Select Add Key to open Key Details screen.
  3. Add key Description.
  4. Select User you would like to generate a key for in the dropdown.
  5. Select access priviledge for this API key — Read access, Write access or Read/Write access.
  6. Select Generate API Key to generate the key.

alt text

Once key is generated, you should see Consumer key and Consumer secret keys, a QRCode.

alt text

Please copy these keys for later use in next step in the application configuration. You should save this API key in a safe place since WooCommerce won't show it again after you close this windows.

tip

To learn more about WooCommerce REST API: WooCommerce REST API Client Library

  • Test if the API is working

Simply open a web browser to http://your-website-url/wp-json/wc/v3, if you can see list of JSON returned meant that the API config is correct. You're ready to move to next step.

Step 2: Install the required plugins

Below are plugins required to work with XStore:

  • Jetpack: This plugin support JSON API, helps client apps access website contents safe and secure.
  • XStore: This plugin support WP login, Google and Facebook login.
  • WP REST API (Version 2): This plugin as it named to provide REST API, supports HTTP. Grab your site’s data in simple JSON format, including users, posts, taxonomies and more. Retrieving or updating data is as simple as sending a HTTP request.
  • Simple JWT Authentication: This plugin extends the WP REST API using JSON Web Tokens Authentication as an authentication method.
note

These plugins are available from the downloaded package at WP-Plugins folder.

After installed, make sure that all plugins are Active. You can use these zip file and install them like other Wordpress plugins.

Step 3: Config Simple JWT Authentication plugin:

1. Enable PHP HTTP Authorization Header

  • Shared Hosts:

Most of the shared hosts have disabled the HTTP Authorization Header by default. To enable this option you'll need to edit your .htaccess file by adding the following:

RewriteEngine on
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]
  • WPEngine:

To enable this option you'll need to edit your .htaccess file by adding the following:

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

2. Configuration

In Wordpress dashboard, go to Settings > Simple JWT Authentication :

alt text

The JWT needs a Secret Key to sign the token. This secret key must be unique and never revealed.

You can use a string from here https://api.wordpress.org/secret-key/1.1/salt/

Step 4: Upload Store config file

Go to Wordpress dashboard, Media > Add New

alt text

Browse to Store.txt file in the downloaded package and start the upload. When upload is done, go to Media > Library and find the uploaded Store file

alt text

Click on the file name title Store

alt text

Take note the file URL, this URL will be used to config Mobile App at next step.


Following step 5 is optional, do this step only if you want to create sample Wordpress posts and categories look exactly with our Demo.

Step 5: Import Wordpress posts demo content (optional)

Go to Wordpress dashboard, select Tools > Import > Wordpress, click Run Importer to open Import Wordpress window.

alt text

Browse to extracted downloaded package, choose temple .xml file under Posts folder for posts and categories sample, and folder Products for sample products, finally click Upload file and import.

Your Wordpress site is now ready. Let setup the mobile app connection.

b. Mobile Application Setup

After Woocomerce website is setup with all required plugins are installed and well configured, you're now ready to setup XStore mobile application.

This section guide how to setup mobile app to connect and work with WooCommerce website installed in previous step.

  • Step 1: Config Wordpress site URL:

Open GlobalSettings.cs file, find the below code line, replace the URL with your site URL in previous step.

static GlobalSettings()
{
// Wordpress site URL
defaultServerEndpoint = "https://coffeestore.tlssoftwarevn.com";
}
important

If you'setting the website in local machine, please make sure that you use the local IP address, for example: http://192.128.1.15, please do not use localhost string, this will cause failed connection.

  • Step 2: Change WooCommerce REST API key:

Open GlobalSettings.cs file, find the below code line, replace the WooCommerceConsumerKey and WooCommerceConsumerSecret with your new key.

/// <summary>
/// Woocommerce REST API Key value
/// </summary>
public static string WooCommerceConsumerKey = "ck_4f9cdee80a13ed2ba72a71b15ff8a41ee8545cb3";
public static string WooCommerceConsumerSecret = "cs_c22810541374dd69b482648b064f626e0b705ca5";
  • Step 3: Change Store Info endpoint:

Open GlobalSettings.cs file, find the below code line, replace with your uploaded Store URL at previous step:

public static string StoreInfoEndpoint => $"{defaultServerEndpoint}/wp-content/uploads/2020/05/Store.txt";

Finally, click Build > Rebuild Solution, then Click the Debug button to deploy the application to the Android emulator or your physical android phone.


4. Next Step

Go to next Customization to know more about how to customize the design/interface of your app.

Then go to Publish to Appstore or GooglePlay

During installation, if you got any issue, please 1st go to Common Questions to see list of common issues and solutions to fix it.