Skip to content

Commit 525451a

Browse files
fscelliottfscelliott
committed
adding SDK guides for readme.io
1 parent 39f7409 commit 525451a

20 files changed

+1796
-0
lines changed

‎docs/010 - install-sdk-csharp.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: "Install SDK"
3+
slug: "install-sdk-csharp"
4+
hidden: false
5+
createdAt: "2019-09-11T13:55:51.015Z"
6+
updatedAt: "2019-09-11T13:58:07.201Z"
7+
---
8+
The C# SDK is distributed through NuGet.
9+
10+
For Windows, to install, run the command `Install-Package Optimizely.SDK` in the Package Manager Console:
11+
[block:code]
12+
{
13+
"codes": [
14+
{
15+
"code": "PM> Install-Package Optimizely.SDK -Version 3.0.0\n\n",
16+
"language": "shell",
17+
"name": "Install the SDK"
18+
}
19+
]
20+
}
21+
[/block]
22+
The package is on NuGet at https://www.nuget.org/packages/Optimizely.SDK. The full source code is at https://github.com/optimizely/csharp-sdk.

‎docs/020 - initialize-sdk-csharp.md

+253
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
---
2+
title: "Initialize SDK"
3+
slug: "initialize-sdk-csharp"
4+
hidden: false
5+
createdAt: "2019-09-11T14:15:47.848Z"
6+
updatedAt: "2020-04-10T00:11:24.283Z"
7+
---
8+
Use the `instantiate` method to initialize the C# SDK and instantiate an instance of the Optimizely client class that exposes API methods like [Get Enabled Features](doc:get-enabled-features-csharp). Each client corresponds to the datafile representing the state of a project for a certain environment.
9+
[block:api-header]
10+
{
11+
"title": "Version"
12+
}
13+
[/block]
14+
SDK v3.2.0
15+
[block:api-header]
16+
{
17+
"title": "Description"
18+
}
19+
[/block]
20+
The constructor accepts a configuration object to configure Optimizely.
21+
22+
Some parameters are optional because the SDK provides a default implementation, but you may want to override these for your production environments. For example, you may want override these to set up an [error handler](doc:customize-error-handler-csharp) and [logger](doc:customize-logger-csharp) to catch issues, an event dispatcher to manage network calls, and a User Profile Service to ensure sticky bucketing.
23+
[block:api-header]
24+
{
25+
"title": "Parameters"
26+
}
27+
[/block]
28+
The table below lists the required and optional parameters in C#.
29+
[block:parameters]
30+
{
31+
"data": {
32+
"h-0": "Parameter",
33+
"h-1": "Type",
34+
"h-2": "Description",
35+
"0-0": "**datafile**\n*optional* ",
36+
"0-1": "string",
37+
"0-2": "The JSON string representing the project.",
38+
"1-0": "**configManager**\n*optional*",
39+
"1-1": "ProjectConfigManager",
40+
"1-2": "The project config manager provides the project config to the client.",
41+
"2-0": "**eventDispatcher**\n*optional*",
42+
"2-1": "IEventDispatcher",
43+
"2-2": "An event handler to manage network calls.",
44+
"3-0": "**logger**\n*optional*",
45+
"3-1": "ILogger",
46+
"3-2": "A logger implementation to log issues.",
47+
"4-0": "**errorHandler**\n*optional*",
48+
"4-1": "IErrorHandler",
49+
"4-2": "An error handler object to handle errors.",
50+
"5-0": "**userProfileService**\n*optional*",
51+
"5-1": "UserProfileService",
52+
"5-2": "A user profile service.",
53+
"6-0": "**skipJsonValidation**\n*optional*",
54+
"6-1": "boolean",
55+
"6-2": "Specifies whether the JSON should be validated. Set to `true` to skip JSON validation on the schema, or `false` to perform validation."
56+
},
57+
"cols": 3,
58+
"rows": 7
59+
}
60+
[/block]
61+
62+
[block:api-header]
63+
{
64+
"title": "Returns"
65+
}
66+
[/block]
67+
Instantiates an instance of the Optimzely class.
68+
[block:api-header]
69+
{
70+
"title": "Automatic datafile management (ADM)"
71+
}
72+
[/block]
73+
Optimizely provides out-of-the-box functionality to dynamically manage datafiles (configuration files) on either the client or the server. The C# SDK provides default implementations of an Optimizely `ProjectConfigManager`. The package also includes a factory class, OptimizelyFactory, which you can use to instantiate the Optimizely SDK with the default configuration of HttpProjectConfigManager.
74+
75+
Whenever the experiment configuration changes, the SDK uses automatic datafile management (ADM) to handle the change for you. In the C# SDK, you can provide either `sdkKey` or `datafile` or both.
76+
77+
* When initializing with just the SDK key, the SDK will poll for datafile changes in the background at regular intervals.
78+
* When initializing with just the datafile, the SDK will NOT poll for datafile changes in the background.
79+
* When initializing with both the SDK key and datafile, the SDK will use the given datafile and start polling for datafile changes in the background.
80+
81+
### Basic example
82+
83+
The following code example shows basic C# ADM usage.
84+
[block:code]
85+
{
86+
"codes": [
87+
{
88+
"code": "using OptimizelySDK;\n\npublic class App\n{\n public static void Main(string[] args)\n {\n string sdkKey = args[0];\n \t Optimizely optimizely = OptimizelyFactory.NewDefaultInstance(sdkKey);\n }\n}\n\n",
89+
"language": "csharp"
90+
}
91+
]
92+
}
93+
[/block]
94+
### Advanced examples
95+
96+
97+
[block:callout]
98+
{
99+
"type": "warning",
100+
"body": "If you are configuring a logger, make sure to pass it into the `ProjectConfigManager` instance as well."
101+
}
102+
[/block]
103+
In the C# SDK, you only need to pass the SDK key value to instantiate a client. Whenever the experiment configuration changes, the SDK handles the change for you.
104+
105+
Include `sdkKey` as a string property in the options object you pass to the `createInstance` method.
106+
107+
When you provide the `sdkKey`, the SDK instance downloads the datafile associated with that `sdkKey`. When the download completes, the SDK instance updates itself to use the downloaded datafile.
108+
[block:callout]
109+
{
110+
"type": "warning",
111+
"title": "",
112+
"body": "Pass all components (Logger, ErrorHandler, NotificationCenter) to the Optimizely constructor. Not passing a component will fail to enable its respective functionality. In other words, components only work when passed to the constructor."
113+
}
114+
[/block]
115+
116+
[block:code]
117+
{
118+
"codes": [
119+
{
120+
"code": "// Initialize with SDK key and default configuration\nvar sdkKey = \"<Your_SDK_Key>\" // replace with your own SDK Key\nOptimizely optimizely = OptimizelyFactory.newDefaultInstance(sdkKey);\n\n\n// You can also customize the SDK instance with custom configuration. In this example we are customizing the project config manager to poll every 5 minutes for the datafile.\nvar projectConfigManager =\n new HttpProjectConfigManager.Builder()\n .WithSdkKey(sdkKey)\n .WithPollingInterval(TimeSpan.FromMinutes(5))\n // .WithLogger(logger) - this is needed if you are configuring a logger for the optimizely instance\n// .WithErrorHandler(errorHandler) - this is needed if you are configuring an errorhandler for the optimizely instance.\n// .WithNotificationCenter(notificationCenter) this is needed if you are subscribing config update\n .Build();\n\nvar Optimizely = new Optimizely(projectConfigManager);\n\n// Initialize with Logger\n// var Optimizely = new Optimizely(projectConfigManager, logger: logger);\n\n// Initialize with Logger, ErrorHandler\n// var Optimizely = new Optimizely(projectConfigManager, errorHandler: errorHandler, logger: logger);\n\n// Initialize with NotificationCenter, Logger, ErrorHandler\n// var Optimizely = new Optimizely(projectConfigManager, notificationCenter: NotificationCenter, errorHandler: errorHandler, logger: logger);\n\n// Note: Use OptimizelyFactory NewDefaultInstance method to use same logger, errorHandler and notificationCenter for all of its Components (Optimizely, EventProcessor, HttpProjectConfigManager)\n",
121+
"language": "csharp"
122+
}
123+
]
124+
}
125+
[/block]
126+
Here is a code example showing advanced configuration for C# ADM. Advanced configuration properties are described in the sections below. This advanced example shows how to construct the individual components directly to override various configurations. This gives you full control over which implementations to use and how to use them.
127+
[block:code]
128+
{
129+
"codes": [
130+
{
131+
"code": "using OptimizelySDK;\nusing OptimizelySDK.Config;\n\npublic class App\n{\n public static void Main(string[] args)\n {\n string sdkKey = args[0];\n // You can also use your own implementation of the ProjectConfigManager interface\n ProjectConfigManager projectConfigManager =\n new HttpProjectConfigManager.Builder()\n\t .WithSdkKey(sdkKey)\n\t .WithPollingInterval(TimeSpan.FromMinutes(1))\n\t .Build();\n\n Optimizely optimizely = new Optimizely(configManager);\n }\n}\n\n",
132+
"language": "csharp"
133+
}
134+
]
135+
}
136+
[/block]
137+
### HttpProjectConfigManager
138+
139+
[HttpProjectConfigManager](https://github.com/optimizely/csharp-sdk/blob/fahad/dfm-readme/OptimizelySDK/Config/HttpProjectConfigManager.cs) is an implementation of the abstract [PollingProjectConfigManager](https://github.com/optimizely/csharp-sdk/blob/master/OptimizelySDK/Config/PollingProjectConfigManager.cs). The `Poll` method is extended and makes an HTTP `GET` request to the configured URL to asynchronously download the project datafile and initialize an instance of the `ProjectConfig`.
140+
141+
By default, `HttpProjectConfigManager` will block until the first successful datafile retrieval, up to a configurable timeout. Set the frequency of the polling method and the blocking timeout with `HttpProjectConfigManager.Builder`.
142+
[block:code]
143+
{
144+
"codes": [
145+
{
146+
"code": "ProjectConfigManager projectConfigManager =\n new HttpProjectConfigManager.Builder()\n\t .WithSdkKey(sdkKey)\n\t .WithPollingInterval(TimeSpan.FromMinutes(1))\n\t .Build();\n\n",
147+
"language": "csharp"
148+
}
149+
]
150+
}
151+
[/block]
152+
#### SDK key
153+
154+
The SDK key is used to compose the outbound HTTP request to the default datafile location on the Optimizely CDN.
155+
156+
#### Polling interval
157+
158+
The polling interval is used to specify a fixed delay between consecutive HTTP requests for the datafile. The valid interval duration is between 1 to 4294967294 milliseconds.
159+
160+
#### Initial datafile
161+
162+
You can provide an initial datafile via the builder to bootstrap the `ProjectConfigManager` so that it can be used immediately without blocking execution. The initial datafile also serves as a fallback datafile if HTTP connection cannot be established. This is useful in mobile environments, where internet connectivity is not guaranteed.
163+
164+
The initial datafile will be discarded after the first successful datafile poll.
165+
166+
#### Builder methods
167+
168+
Use the following builder methods to customize the `HttpProjectConfigManager` configuration.
169+
[block:parameters]
170+
{
171+
"data": {
172+
"0-0": "**WithDatafile(string)**",
173+
"1-0": "**WithUrl(string)**",
174+
"2-0": "**WithFormat(string)**",
175+
"3-0": "**WithPollingInterval(TimeSpan)**",
176+
"0-1": "null",
177+
"1-1": "null",
178+
"2-1": "null",
179+
"3-2": "Fixed delay between fetches for the datafile",
180+
"3-1": "5 minutes",
181+
"1-2": "URL override location used to specify custom HTTP source for the Optimizely datafile",
182+
"0-2": "Initial datafile, typically sourced from a local cached source",
183+
"2-2": "Parameterized datafile URL by SDK key",
184+
"4-0": "**WithBlockingTimeoutPeriod(TimeSpan)**",
185+
"4-1": "15 seconds",
186+
"h-0": "Property",
187+
"h-1": "Default value",
188+
"h-2": "Description",
189+
"4-2": "Maximum time to wait for initial bootstrapping. The valid timeout duration is 1 to 4294967294 milliseconds.",
190+
"5-0": "**WithSdkKey(string)**",
191+
"5-1": "null",
192+
"5-2": "Optimizely project SDK key; required unless source URL is overridden"
193+
},
194+
"cols": 3,
195+
"rows": 6
196+
}
197+
[/block]
198+
#### Update config notifications
199+
200+
A notification signal will be triggered whenever a new datafile is fetched. To subscribe to these notifications, use method `NotificationCenter.AddNotification()`.
201+
[block:code]
202+
{
203+
"codes": [
204+
{
205+
"code": "optimizely.NotificationCenter.AddNotification(\n NotificationCenter.NotificationType.OptimizelyConfigUpdate,\n () => Console.WriteLine(\"Received new datafile configuration\")\n);\n\n",
206+
"language": "csharp"
207+
}
208+
]
209+
}
210+
[/block]
211+
### OptimizelyFactory
212+
213+
[OptimizelyFactory](https://github.com/optimizely/csharp-sdk/blob/fahad/dfm-readme/OptimizelySDK/OptimizelyFactory.cs) provides basic utility to instantiate the Optimizely SDK with a minimal number of configuration options.
214+
215+
OptimizelyFactory does not capture all configuration and initialization options. For more use cases, build the resources with their constructors.
216+
217+
You must provide the SDK key at runtime, directly via the factory method:
218+
[block:code]
219+
{
220+
"codes": [
221+
{
222+
"code": "Optimizely optimizely = OptimizelyFactory.NewDefaultInstance(<<SDK_KEY>>);\n\n",
223+
"language": "csharp"
224+
}
225+
]
226+
}
227+
[/block]
228+
229+
[block:api-header]
230+
{
231+
"title": "Instantiate using datafile"
232+
}
233+
[/block]
234+
You can also instantiate with a hard-coded datafile. If you don't pass in an SDK key, the Optimizely Client will not automatically sync newer versions of the datafile. Any time you retrieve an updated datafile, just re-instantiate the same client.
235+
236+
For simple applications, all you need to provide to instantiate a client is a datafile specifying the project configuration for a given environment. For most advanced implementations, you'll want to [customize the logger](doc:customize-logger-csharp) or [error handler](doc:customize-error-handler-csharp) for your specific requirements.
237+
[block:code]
238+
{
239+
"codes": [
240+
{
241+
"code": "using OptimizelySDK;\n\n// Instantiate an Optimizely client\nvar datafile = \"<Datafile_JSON_string>\"\nOptimizely OptimizelyClient = new Optimizely(datafile);\n\n",
242+
"language": "csharp"
243+
}
244+
]
245+
}
246+
[/block]
247+
248+
[block:api-header]
249+
{
250+
"title": "Source files"
251+
}
252+
[/block]
253+
The language/platform source files containing the implementation for C# are at [Optimizely.cs](https://github.com/optimizely/csharp-sdk/blob/master/OptimizelySDK/Optimizely.cs).

‎docs/030 - example-usage-csharp.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: "Example usage"
3+
slug: "example-usage-csharp"
4+
hidden: true
5+
createdAt: "2019-09-11T22:26:38.446Z"
6+
updatedAt: "2019-09-12T20:28:26.570Z"
7+
---
8+
Once you've installed the C# SDK, import the Optimizely library into your code, get your Optimizely project's datafile, and instantiate a client. Then, you can use the client to evaluate feature flags, activate an A/B test, or feature test.
9+
10+
This example demonstrates the basic usage of each of these concepts. This example shows how to:
11+
1. Evaluate a feature with the key `price_filter` and check a configuration variable on it called `min_price`. The SDK evaluates your feature test and rollouts to determine whether the feature is enabled for a particular user, and which minimum price they should see if so.
12+
13+
2. Run an A/B test called `app_redesign`. This experiment has two variations, `control` and `treatment`. It uses the `activate` method to assign the user to a variation, returning its key. As a side effect, the activate function also sends an impression event to Optimizely to record that the current user has been exposed to the experiment.
14+
15+
3. Use event tracking to track an event called `purchased`. This conversion event measures the impact of an experiment. Using the track method, the purchase is automatically attributed back to the running A/B and feature tests we've activated, and the SDK sends a network request to Optimizely via the customizable event dispatcher so we can count it in your results page.
16+
[block:code]
17+
{
18+
"codes": [
19+
{
20+
"code": "//Import Optimizely SDK\nusing OptimizelySDK;\n\n// Instantiate an Optimizely client\nvar optimizelyClient = new Optimizely(datafile);\n\n// Evaluate a feature flag and a variable\nbool isFeatureEnabled = optimizelyClient.IsFeatureEnabled(\"price_filter\", userId);\nint? min_price = optimizelyClient.GetFeatureVariableInteger(\"price_filter\", \"min_price\", userId);\n\n// Activate an A/B test\nvar variation = optimizelyClient.Activate(\"app_redesign\", userId);\n\tif (variation != null && !string.IsNullOrEmpty(variation.Key))\n\t{\n\t\tif (variation.Key == \"control\")\n\t\t{\n\t\t\t// Execute code for variation A\n\t\t}\n\t\telse if (variation.Key == \"treatment\")\n\t\t{\n\t\t\t// Execute code for variation B\n\t\t}\n\t}\n\telse\n\t{\n\t\t// Execute code for your users who don’t qualify for the experiment\n\t}\n\n// Track an event\noptimizelyClient.Track(\"purchased\", userId);\n\n",
21+
"language": "csharp"
22+
}
23+
]
24+
}
25+
[/block]

0 commit comments

Comments
 (0)