|
1 | 1 | # Optimizely Android SDK |
2 | | -Master<br/> |
3 | | -[](https://travis-ci.org/optimizely/android-sdk) |
4 | | -<br/> |
5 | | -<br/> |
6 | 2 | [](http://www.apache.org/licenses/LICENSE-2.0) |
| 3 | +[](https://travis-ci.org/optimizely/android-sdk) |
| 4 | + |
7 | 5 | ## Overview |
8 | 6 |
|
9 | | -This repository houses the Android SDK for use with Optimizely Full Stack and Optimizely Rollouts. This repo depends on the [Optimizely Java SDK](https://github.com/optimizely/java-sdk). |
| 7 | +This repository houses the Android SDK for use with Optimizely Full Stack and Optimizely Rollouts. The Android SDK depends on the [Optimizely Java SDK](https://github.com/optimizely/java-sdk). |
10 | 8 |
|
11 | 9 | Optimizely Full Stack is A/B testing and feature flag management for product development teams. Experiment in any application. Make every feature on your roadmap an opportunity to learn. Learn more at https://www.optimizely.com/platform/full-stack/, or see the [documentation](https://docs.developers.optimizely.com/full-stack/docs). |
12 | 10 |
|
13 | 11 | Optimizely Rollouts is free feature flags for development teams. Easily roll out and roll back features in any application without code deploys. Mitigate risk for every feature on your roadmap. Learn more at https://www.optimizely.com/rollouts/, or see the [documentation](https://docs.developers.optimizely.com/rollouts/docs). |
14 | 12 |
|
| 13 | +## Getting Started |
| 14 | + |
| 15 | +### Using the SDK |
| 16 | +See the [Mobile developer documentation](https://docs.developers.optimizely.com/full-stack/docs/install-sdk-android) to learn how to set |
| 17 | +up an Optimizely X project and start using the SDK. |
| 18 | + |
| 19 | +### Requirements |
| 20 | +* Android API 14 or higher |
| 21 | + |
| 22 | +### Installing the SDK |
| 23 | +To add the android-sdk and all modules to your project, include the following in your app's `build.gradle`: |
| 24 | + |
| 25 | +``` |
| 26 | +repositories { |
| 27 | + jcenter() |
| 28 | +} |
| 29 | +
|
| 30 | +dependencies { |
| 31 | + implementation 'com.optimizely.ab:android-sdk:3.5.0' |
| 32 | +} |
| 33 | +``` |
| 34 | + |
| 35 | +### Samples |
| 36 | +A sample code for SDK initialization and experiments: |
| 37 | + |
| 38 | +``` |
| 39 | +OptimizelyManager optimizelyManager = OptimizelyManager.builder() |
| 40 | + .withSDKKey("my_sdk_key") |
| 41 | + .withDatafileDownloadInterval(TimeUnit.MINUTES.toSeconds(15)) |
| 42 | + .build(getApplicationContext()); |
| 43 | + |
| 44 | +optimizelyManager.initialize(this, null, (OptimizelyClient optimizely) -> { |
| 45 | + OptimizelyClient optimizely = optimizelyManager.getOptimizely(); |
| 46 | + |
| 47 | + Variation variation = optimizely.activate("background_experiment", userId); |
| 48 | + |
| 49 | + optimizely.track("sample_conversion", userId); |
| 50 | +}); |
| 51 | +
|
| 52 | +``` |
| 53 | + |
15 | 54 | ## Architecture |
16 | 55 |
|
17 | | -This project has 5 modules. Each module has source in `<module>/src/main/java` |
18 | | -and test source in `<module>src/main/androidTest`. The build is configured |
19 | | -in the `build.gradle` for each module. The `settings.gradle` in the project |
20 | | -root declares modules. The `build.gradle` in the project root has build |
21 | | -config common for all modules. |
| 56 | +This project includes 5 library modules and a test app. |
22 | 57 |
|
23 | 58 | 1. Android SDK |
24 | | - - Users who want all modules should declare a dependency on this module |
25 | | - - This is the outer module that depends on all other modules |
26 | | - - Handles downloading the Optimizely datafile and building Optimizely objects |
27 | | - - Delivers the built Optimizely object to listeners and caches it in memory |
28 | | -2. Event Handler |
29 | | - - Handles dispatching events to the Optimizely backend |
30 | | - - Uses a Service so events can be sent without the app being re-opened |
31 | | - - Persists events in a SQLite3 database |
32 | | - - Required to be implemented by the Optimizely Java core |
33 | | -3. User Profile |
34 | | - - Optional implementation for Optimizely Java core |
35 | | - - Makes bucketing persistent |
36 | | - - Once a user is bucketed in an variation they will remain in that variation |
37 | | -4. Shared |
| 59 | + - Users who want all modules should declare a dependency on this module. |
| 60 | + - This is the outer module that depends on all other modules. |
| 61 | + - This builds Optimizely objects and provides all public APIs. |
| 62 | +2. Datafile Handler |
| 63 | + - This handles downloading the datafile from the Optimizely server. |
| 64 | +3. Event Handler |
| 65 | + - This handles dispatching events to the Optimizely server. |
| 66 | + - This uses a Service so events can be sent without the app being re-opened. |
| 67 | + - Events remain persistent until dispatching completed successfully. |
| 68 | +4. User Profile |
| 69 | + - Persistent bucketing |
| 70 | + - Once a user is bucketed in a variation, the user will remain in that variation. |
| 71 | +5. Shared |
38 | 72 | - Common utils for all modules |
39 | | -5. Test App |
40 | | - - Built against the source of all modules |
41 | | - - Simple app showing how to use Android Optimizely |
| 73 | +6. Test App |
| 74 | + - A simple app showing how to use the Optimizely Android SDK |
42 | 75 |
|
43 | | -## Developing |
| 76 | +## Development |
44 | 77 |
|
45 | 78 | ### Command Line |
46 | 79 |
|
47 | 80 | 1. Clone the repo |
48 | 81 | * `git clone [email protected]:optimizely/android-sdk.git` |
49 | | -3. Create, or use an existing, Optimizely Android project |
50 | | -4. Build the project (from the project root) |
| 82 | +2. Create, or use an existing, Optimizely Android project |
| 83 | +3. Build the project (from the project root) |
51 | 84 | * `./gradlew assemble` |
52 | | -5. Run tests for all modules |
| 85 | +4. Run tests for all modules |
53 | 86 | * `./gradlew testAllModules` |
54 | | - * A device or emulator must be connected |
55 | | -6. Install the test app onto all connected devices and emulators |
| 87 | + * A device or emulator must be connected. |
| 88 | +5. Install the test app onto all connected devices and emulators |
56 | 89 | * `./gradlew test-app:installDebug` |
57 | | - * The test app depends on all of the other project modules |
58 | | - * The modules are built from source |
59 | | - * Changes in any modules source will be applied to the test app on the next build |
60 | | -7. Discover more gradle tasks |
| 90 | + * The test app depends on all of the other project modules. |
| 91 | + * The modules are built from source. |
| 92 | +6. Discover more gradle tasks |
61 | 93 | * `./gradlew tasks` |
62 | | - * To see the task of an individual module |
63 | | - * `./gradlew user-profile:tasks` |
| 94 | + * To see the task of an individual module: `./gradlew user-profile:tasks` |
64 | 95 |
|
65 | 96 | ### Android Studio |
66 | 97 |
|
67 | | -Android Studio is an IDE that wraps gradle (and `adb`). Everything you can do in Android Studio can be done from command line with gradle and the other android command line tools. |
| 98 | +Android Studio is an IDE that wraps gradle. Everything you can do in Android Studio can be done from the command line tools. |
68 | 99 |
|
69 | 100 | You can import this project into Android Studio by opening Android Studio and selecting `Import Project` from the first dialog or from the `File` menu. Simply select the project's root `build.gradle` file and Android Studio will do the rest. |
70 | 101 |
|
71 | 102 | Tests can be run by right clicking the file in the project pane or by clicking the method name in source and selecting run. You will be prompted to create an AVD or connect a device if one isn't connected. |
72 | 103 |
|
73 | | -## Releasing |
74 | | - |
75 | | -The default branch is devel. Feature branch PRs are automatically made against it. When PRs are reviewed and pass checks they should be squashed and merged into devel. Devel will be built and tested for each commit. |
76 | | - |
77 | | -Versions are managed via git tags. Tags can be created from the command line or from the Github UI. |
78 | | - |
79 | | -Snapshot builds are made off of the beta branch. Travis will test all commits to this branch. When a commit is tagged and pushed, Travis will build, test, *and*, ship the build to Bintray. The version name used |
80 | | -is the name of the tag. For snapshot builds the version should have `-SNAPSHOT` appended. For example `0.1.2-SNAPSHOT`. Multiple builds with the same version can be pushed to Bintray when using snapshot versions. |
81 | | -This keeps the version number from increasing too quickly for beta builds. Grade and maven ensure that users are on the latest snapshot via timestamps. |
82 | | -There can be only one git tag per version name so snapshot tags may need to be moved. For example `git tag -f -a 0.1.2` and `git push -f --tags`. |
83 | | - |
84 | | -Release builds are made off of the master branch. Travis will test all commits to this branch. Just like the beta branch, pushing a tag will trigger a build, tests, and release of the version of the tag to Bintray. |
85 | | -For example, to release version 0.1.2 you need to pull devel, checkout master, pull master, fast-forward master to devel, push master, then release 0.1.2 on Github, which creates a tag. You could also run |
86 | | -`git tag -a 0.1.2 -m 'Version 0.1.2`. The argument to `-a` is the actual version name used on Bintray so it must be exact. Then run `git push --tags` to trigger Travis. |
87 | | - |
88 | | -*Note:* only Optimizely employees can push to master, beta, and devel branches. |
89 | | - |
90 | | -## Contributing |
| 104 | +### Contributing |
91 | 105 | Please see [CONTRIBUTING](CONTRIBUTING.md). |
92 | 106 |
|
93 | 107 | ### Credits |
|
0 commit comments