Warning

This site is no longer being maintained. Visit the eDocs documentation portal for updated information.

Visit eDocs
Dismiss message

Android

Created by María Rubiera · last update September 8, 2020

Step-by-step guide

IMPORTANT - Min Android supported is 5.0 (API 21)

Integrating X into your app is a straightforward process that consists of three steps:

  1. Add Empathy dependency to your Gradle
  2. Start EmpathyClient
  3. Add the Empathy components you want to use in your app

1. Add Empathy dependency to your Gradle files

Empathy Nexus is not a high availability system so to avoid unexpected errors in your builds we recommend to have a mirror repository on your side.

  1. Add repository

    You will need to set up our secured repository to be able to download internal packages from the url : https://nexus.empathybroker.com/repository/public

    To handle repository connection credentials you could review official gradle documentation, all needed credentials ( username and password ) will be provided by Empathy.

  2. Add dependency

And add the Gradle dependency (artifactId will be provided by Empathy with your customised X Apps version):

- Groovy:

1
2
3
4

   dependencies {
     ...
     implementation 'co.empathy.mobile:{artifactId}:1.0.0'
   }

- Kotlin DSL:

1
2
3
4

   dependencies {
     ...
     implementation("co.empathy.mobile:{artifactId}:1.0.0")
   }

2. Empathy Client

Initialize

The second step for integrating X Apps is setting up the EmpathyClient instance.

- Java:

1
2
3
4
5
6
7
8

public class YourApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        EmpathyClient.INSTANCE.initialize(this);
        ...
    }
}

- Kotlin:

1
2
3
4
5
6
7

open class YourApp : Application() {
    override fun onCreate() {
        super.onCreate()
        EmpathyClient.initialize(this)
        ...
    }
}

Dynamic configurations

EmpathyClient initialization function could receive a configuration object.

- Java:

1
2
3
4
5
6
7
8

public class YourApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        EmpathyClient.INSTANCE.initialize(this, new MyEmpathyConfiguration());
        ...
    }
}

- Kotlin:

1
2
3
4
5
6
7

open class YourApp : Application() {
    override fun onCreate() {
        super.onCreate()
        EmpathyClient.initialize(this, MyEmpathyConfiguration)
        ...
    }
}

This configuration object extends ClientConfiguration class.

- Java:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

public class MyEmpathyConfiguration extends ClientConfiguration {

    @NotNull
    @Override
    public String getInstance() {
        return "<your-value-here>";
    }

    @NotNull
    @Override
    public String getEnvironment() {
        return "<your-value-here>";
    }

    @NotNull
    @Override
    public ConfigurationParameter getLang() {
        return new ConfigurationParameter("<your-key-here>", "<your-value-here>");
    }

    @Nullable
    @Override
    public ConfigurationParameter getCatalogue() {
        return new ConfigurationParameter("<your-key-here>", "<your-value-here>");
    }

    @Nullable
    @Override
    public ConfigurationParameter getStore() {
        return new ConfigurationParameter("<your-key-here>", "<your-value-here>");
    }

    @Nullable
    @Override
    public ConfigurationParameter getWarehouse() {
        return new ConfigurationParameter("<your-key-here>", "<your-value-here>");
    }

    @Nullable
    @Override
    public List<ConfigurationParameter> getExtra() {
        return Arrays.asList(
                new ConfigurationParameter(
                        "<your-extra-key-here>",
                        "<your-extra-value-here>"),
                new ConfigurationParameter(
                        "<your-extra-key-here>",
                        "<your-extra-value-here>"),
        );
    }
}

- Kotlin:

1
2
3
4
5
6
7
8
9
10
11
12
13

object MyEmpathyConfiguration : ClientConfiguration() {
    override val instance: String = "<your-value-here>"
    override val environment: String = "<your-value-here>"
    override val lang = ConfigurationParameter("<your-key-here>", "<your-value-here>")
    override val catalog: ConfigurationParameter? = null
    override val store: ConfigurationParameter = ConfigurationParameter("<your-key-here>", "<your-value-here>") 
    override val warehouse: ConfigurationParameter? = null
    override val extra: List<ConfigurationParameter> =
        listOf(
            ConfigurationParameter("<your-key-here>", "<your-value-here>"),
            ConfigurationParameter("<your-key-here>", "<your-value-here>")
        )
}

This is the list of parameters that are currently supported:

Parameter Type Required Default Description
instance string Yes 'eb-demo' Unique identifier of your Search API instance. It is provided by Empathy
environment string Yes '' Default value indicates production environment

Use staging for pre-production environment
lang ConfigurationParameter Yes 'es' Language to be used by X for internationalizing messages (i.e. language of the search interface).

If there are no translations for the specified language, the fallback language ('es') will be used.
catalogue ConfigurationParameter No null Catalogue identifier used by X when querying the Search API.

Not applicable to all instances.
store ConfigurationParameter No null Store identifier used by X when querying the Search API.

Not applicable to all instances.
warehouse ConfigurationParameter No null Warehouse identifier used by X when querying the Search API.

Not applicable to all instances.
extra List<ConfigurationParameter> No null Add extra ConfigurationParameter.

Not applicable to all instances.

3. Empathy Components

Configure your components

Every component has some attributes to configure itself. Take a look at the component you need to configure to see the complete list of attributes.

You can set the values in the xml, see lines 7 to 9 in the example:

1
2
3
4
5
6
7
8
9
10
11
12

<co.empathy.x.client.ui.view.SearchBoxView
    android:id="@+id/searchBox"
    style="@style/EmpathySearchBoxLight"
    android:layout_width="0dp"
    android:layout_height="wrap_content"
    android:layout_margin="8dp"
    app:hint="Empathy Hint"
    app:hintColor="@color/blue"
    app:textColor="@color/orange"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent" />

Or you can set the values in your code:

- Java:

1
2
3
4

SearchBoxView searchBox = findViewById(R.id.searchBox);
...
searchBox.setHintText("Empathy Hint");
searchBox.setHintColor(ContextCompat.getColor(this,R.color.blue));

- Kotlin:

1
2
3
4

val searchBox: SearchBoxView = findViewById(R.id.searchBox)
...
searchBox.hintText = "Empathy Hint"
searchBox.hintColor = ContextCompat.getColor(this,R.color.blue)
Layout

To get a SearchBoxView you need to include the element in your layout.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout 
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <co.empathy.x.client.ui.view.SearchBoxView
        android:id="@+id/searchBox"
        style="@style/EmpathySearchBoxLight"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:layout_margin="8dp"
        app:hint="Empathy Hint"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />











        
</androidx.constraintlayout.widget.ConstraintLayout>
Listener

To get SearchBoxView actions callback. You need to implement SearchBoxView.OnActionListener

- Java:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

public class MainActivity extends AppCompatActivity implements SearchBoxView.OnActionListener {
...

  @Override
  public void onSearchStateChanged(boolean enabled) {
    ...
  }

  @Override
  public void onSearchConfirmed(@Nullable CharSequence text) {
    ...
  }

  @Override
  public void onButtonClicked(int buttonCode) {
    ...
  }
}

- Kotlin:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

class MainActivity : AppCompatActivity(), SearchBoxView.OnActionListener {
...

  override fun onSearchStateChanged(enabled: Boolean) {
     ...
  }
  
  override fun onSearchConfirmed(text: CharSequence?) {
     ...
  }
  
  override fun onButtonClicked(buttonCode: Int) {
     ...
  }
}


Method Parameter Type Description  
onSearchStateChanged enabled boolean Invoked when Search Box View opened or closed.  
onSearchConfirmed text CharSequence Invoked when search is confirmed, suggestion is selected or search button is clicked on the soft keyboard.

Parameter text contains the query.		  
onButtonClicked buttonCode Int Invoked when search, close search or clear search button clicked.

buttonCode possible values:

SEARCH_BUTTON = 1, CLOSE_BUTTON = 2, CLEAR_SEARCH_BUTTON = 3		  
Configuration

This is the list of attributes that are currently supported:

XML Parameter Method Type Description
searchBoxColor setSearchBoxColor (int) color Set search box color
hint setHintText (CharSequence) string Set search box hint text
hintColor setHintColor(int) color Set search box hint text color
textColor setTextColor(int) color Set search box text color
highlightedTextColor setHighlightedTextColor(int) color Set search box text high lighted color