• HOME
  • INTEGRATIONS
  • SDKS
  • GUIDES
  • API DOCS
No results for ""
EXPAND ALL
launchdarkly.com

EDIT ON GITHUB

Apex SDK reference

Read time: 4 minutes
Last edited: Nov 18, 2020
This SDK is in beta

The Apex SDK is currently in beta and undergoing active development. Elements of this SDK may change without notice. Do not use this SDK in production environments.

Overview

This reference guide documents the features available in our Apex SDK, and explains how these features work. If you want to dig even deeper, our SDKs are open source. To learn more, view the source on GitHub or the API documentation. Additionally you can clone and run a sample application that uses this SDK.

Getting started

Building on top of our Getting Started guide, the following steps will get you started with using the LaunchDarkly SDK in your Salesforce Apex application.

The first step is deploying the SDK to Salesforce:

1git clone https://github.com/launchdarkly/apex-server-sdk.git
2cd apex-server-sdk
3sfdx force:source:deploy --targetusername='YOUR TARGET ORG' --sourcepath='force-app'

Initialize the client as follows:

1LDClient client = new LDClient();

Using client, you can check which variation a particular user should receive for a given feature flag.

1LDUser user = new LDUser.Builder('abc').build();
2
3if (client.boolVariation(user, 'your.flag.key', false)) {
4 System.debug('feature is on');
5} else {
6 System.debug('feature is off');
7}

After the SDK is deployed to Salesforce, start the bridge, and you can begin evaluating flags. The bridge must be running in order to receive flag updates and publish events to LaunchDarkly.

LaunchDarkly Salesforce bridge

The Apex server-side SDK is architected differently than our other SDKs. In most of our SDKs, the SDK downloads feature configurations and sends events by itself. The Apex SDK is different because it uses an external bridging application to connect LaunchDarkly and Salesforce.

Because the SDK uses a bridge to handle state management, there is no initialization delay required to download flags. Additionally, the lack of state inside the SDK means that initializing multiple instances of the SDK is not problematic.

The Apex SDK exposes two HTTP endpoints that the bridge uses: /store and /event. The bridge pushes flag updates to Salesforce through one endpoint, and pulls events from Salesforce with the other.

The bridge is a Go application configured with environment variables. The bridge needs authorization for both LaunchDarkly and Salesforce.

To build the bridge from source install Go 1.14 or higher. To install Go, read Go's documentation. Build and run the bridge like this:

1cd bridge && go build .
2
3export LD_SDK_KEY='Your LaunchDarkly SDK key'
4export SALESFORCE_URL='Your Salesforce Apex REST URL'
5export OAUTH_ID='Your Salesforce OAuth Id'
6export OAUTH_SECRET='Your Salesforce OAuth secret'
7export OAUTH_USERNAME='Your Salesforce username'
8export OAUTH_PASSWORD='Your Salesforce password + security token'
9
10./bridge

The logs indicate if the bridge is running. If it fails, the logs show the errors that occurred. You must deploy the SDK to Salesforce before you run the bridge.

Customizing your client

You can also pass other custom parameters to the client with the configuration object:

1LDConfig config = new LDConfig.Builder()
2 .setAllAttributesPrivate(true)
3 .build();

Here, we've customized the client to redact all user attributes in events.

To learn more about the configuration options available for this SDK, read the API documentation.

Users

Feature flag targeting and rollouts are all determined by the user you pass to your variation calls.

1LDUser user = new LDUser.Builder('aa0ceb')
2 .setFirstName('Ernestina')
3 .setLastName('Evans')
4 .setEmail('ernestina@example.com')
5 .setCustom(new LDValueObject.Builder()
6 .set('groups', new LDValueArray.Builder()
7 .add(LDValue.of('Google'))
8 .add(LDValue.of('Microsoft'))
9 .build()
10 )
11 .build()
12 )
13 .build();

Let's go through this snippet. The most important attribute is the user key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should uniquely identify each user. You can use a primary key, an e-mail address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

All of the other attributes (like firstName, email, and the custom attributes) are optional. The attributes you specify will automatically appear on our dashboard, meaning that you can start segmenting and targeting users with these attributes.

In addition to built-in attributes like names and e-mail addresses, you can pass us any of your own user data by passing custom attributes, like the groups attribute in the example above.

Custom attributes are one of the most powerful features of LaunchDarkly. They let you target users according to any data that you want to send to us, including organizations, groups, and account plans. Anything you pass to us becomes available instantly on our dashboard.

Variation

The variation family of methods determine the flag value for a specific user. In Apex, there is a variation method for each type (e.g. boolVariation, stringVariation, etc).

1Boolean value = client.boolVariation(user, 'your.feature.key', false);

The functions take an LDUser, feature flag key, and a default value.

The default value only returns if an error occurs. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified.

Evaluation details

By passing an LDClient.EvaluationDetail object to a variation call you can programmatically inspect the reason for a particular evaluation. For more information about the nature of the "reason" data, read Evaluation reasons.

1LDClient.EvaluationDetail details = new LDClient.EvaluationDetail();
2
3Boolean value = client.boolVariation(user, 'your.feature.key', false, details);
4
5/* inspect details here */
6if (details.getReason().getKind() == EvaluationReason.Kind.OFF) {
7 /* ... */
8}

AllFlags

The allFlags method produces a map of feature flag keys to their values for a specific user. This does not send any evaluation events to LaunchDarkly.

1Map<String, LDValue> values = client.allFlags(user);

Track

The track method allows you to record actions your users take in your application. In LaunchDarkly, you can tie these events to goals in A/B tests. You can also attach custom JSON data to your event by passing an LDValue parameter to track, or a custom metric value by passing a Double.

1client.track(user, 'your-goal-key', 52.3, LDValue.of('my value'));

Identify

The identify method creates or updates users on LaunchDarkly, making them available for targeting and autocomplete on the dashboard. In most cases, you won't need to call identify. The variation call automatically creates users on the dashboard for you. identify can be useful if you want to pre-populate your dashboard before launching any features.

1client.identify(user);

Anonymous users

You can also distinguish logged-in users from anonymous users in the SDK, as follows:

1LDUser user = new LDUser.Builder('abc123')
2 .setAnonymous(true)
3 .build();

You still need to generate a unique key for anonymous users. Session IDs or UUIDs work best for this.

Anonymous users work just like regular users, except that they won't appear on your Users page in LaunchDarkly. You can't search or autocomplete by anonymous user keys. This is actually a good thing, because it keeps anonymous users from polluting your Users page!

Private user attributes

Optionally, you can configure the Apex SDK to treat some or all user attributes as private user attributes. You can use private user attributes for targeting, but they are redacted from the user data sent back to LaunchDarkly.

In the Apex SDK there are two ways to define private attributes for the LaunchDarkly client:

  • When creating the LDConfig object, you can use setAllAttributesPrivate(true). When you do this, all user attributes (except the key) for the user are redacted before the user is sent to LaunchDarkly.
1LDConfig config = new LDConfig.Builder()
2 .setAllAttributesPrivate(true)
3 .build();
  • You can also define private attribute names on a per-user basis. For example:
1Set<String> privateAttributes = new Set<String>();
2privateAttributes.add('firstName');
3
4LDUser user = new LDUser.Builder('aa0ceb')
5 .setFirstName('alice')
6 .setPrivateAttributeNames(privateAttributes)
7 .build();