Android

Min requirements

• The project is compiled using the min SDK version set to 24

Obtaining an API Key

• The SDK requires some informations in order to validate wheater the client is valid or not as a requirement there are 2 informations IceMobile needs to generate a api key.
• The first is the app signature SHA-1 hash it can be obtained by running the gradle task signingReport, however depending on your computer sdk setup that might be tricky specially with permissions, the easiest way to do that is via the android studio gradle tab by typing signingReport as the image shows.

• The second information is your application id that can be found on your app gradle script.

Adding it to a project

Check the changelog for the latest version

  implementation('com.icemobile:campaign:version')

Or for jetpack compose

  implementation('com.icemobile:campaign-compose:version')

Card number provider

• The CardNumberProvider is the only mandatory piece to initialise the SDK, it is responsible to provide the customer loyalty card number to the campaign so we can apply custom rules for specific customers.
• This method is called outside of the main thread so it is safe to retrieve this number from a network source of from the disk.

class CardNumberProviderImpl: CardNumberProvider {
  override fun get(): String = "client-virtual-card-number"
}

SDK initialization

• This can be called anywhere, but it is recommended in the Application class or via content provider initialization such as the Android initializer.
• This should be called before the first usage of CampaignView class.

IceCampaign.initialize(
  CampaignConfig.Builder(this) //this is a context
      .withCardNumberProvider(CardNumberProviderImpl())
      .build("generated-api-key")
)

Adding it to your views with Android UI Views (for jetpack compose check bellow)

• The CampaignView takes care of load the entire campaign and it is the only widget you need, the width and height are fully customizable, but wrap_content is not really recommended.

  <com.icemobile.campaign.CampaignView
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

Locale provider (optional)

• The LocalProvider offers the ability to override the campaign locale to display the campaign in another language for example.
• By default this method is called with the device language.
• This method is called outside of the main thread, it is useful if the locale needs to be retrieved from a customer profile for example, or if the app has a custom locale override.

class LocaleProviderImpl: LocaleProvider {
  override fun get(): Locale = Locale("")
}

Extra parameter provider (optional)

• The ExtraParameterProvider offers the possibility to send custom headers to the campaign in a key-value format.
• By default implementation returns an empty map.
• This is also called outside of the main thread, it is useful for custom rules for the campaigns or feature flags that needs to be synced between the mobile app and the campaign.
• Note that there are a few headers that we use internally on the sdk such as the Accept-Language the ExtraParameterProvider will not override these headers.

class ExtraParameterProviderImpl: ExtraParameterProvider {
  override fun get(): Map<String, String> = mapOf("custom-key", "custom-value")
}

Authentication provider (optional)

• Provides a custom authentication to the campaign for access in some apis where authentication is required (username / password).
• By default there is no authentication supplied to the campaign.
• This is called outside of the main thread.

class AuthenticationProviderImpl: AuthenticationProvider {
    override fun get(): String = "my-jwt-token"
}

Error handling (optional)

• By default the framework has a standard error view that is displayed when something goes wrong while trying to retrieve the campaign data, such as a network failure, or the campaign is no longer available.
• It is also possible to override this view or the entire error handling using the setErrorHandler in the campaign view.
• If a View is returned in the setErrorHandler unit function then this view will be used as the new error view.
• If null is returned then the standard error view will be used, but, as you get an CampaignView instance as the argument of the error handler you could for example hide the entire campaign if something goes wrong.
• Additionaly the CampaignView class also exposes a reload function that can be used to retry the campaign load

  val campaignView = /* ... */
  campaignView.setErrorHandler { view ->
    null
  }

Jetpack compose

• Jetpack compose support is offered via the compose-module by simply adding the Campaign composable function.

  setContent {
    Campaign()
  }

Jetpack compose error handling

• TBD

SDK detail page customisation (optional)

• We offer trough the SDK the campaign detail which opens a full screen Activity to show more details about the campaign, the navigation of the campaign is then controlled with the SDK.
• By default the detail page uses the application theme so the top actionbar will be fully customised depending on the app current theme, but it is possible to override this if needed.
• If your app doesn't have an action bar the sdk will add a toolbar as action bar using the default theme R.attr.toolbarStyle
• To override the detail page customisation just override the SDK CampaignDetailActivity via manifest, this Activity is a AppCompatActivity so should be straight forward.

<activity
    android:theme="@style/YourCustomTheme"
    android:name="com.icemobile.campaign.CampaignDetailActivity"/>

Proguard

• No proguard configuration is needed 👯