Skip to content

Commit 0eafec3

Browse files
Dynamsoft-JersonDynamsoft-Jerson
committed
add dcp android guide
1 parent d3b513e commit 0eafec3

File tree

1 file changed

+226
-1
lines changed

1 file changed

+226
-1
lines changed

‎programming/android/user-guide/getting-started.md‎

Lines changed: 226 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,229 @@ needGenerateH3Content: true
88
noTitleIndex: true
99
---
1010

11-
# Getting Started with Android Edition
11+
# Dynamsoft Code Parser - Android User Guide
12+
13+
- [Dynamsoft Code Parser - Android User Guide](#dynamsoft-code-parser---android-user-guide)
14+
- [Requirements](#requirements)
15+
- [Add the Libraries](#add-the-libraries)
16+
- [Add the Libraries Manually](#add-the-libraries-manually)
17+
- [Add the Libraries via Maven](#add-the-libraries-via-maven)
18+
- [Build Your First Application](#build-your-first-application)
19+
- [Create a New Project](#create-a-new-project)
20+
- [Include the Library](#include-the-library)
21+
- [Initialize the License](#initialize-the-license)
22+
- [Initialize Code Parser And Parse the Code Bytes](#initialize-code-parser-and-parse-the-code-bytes)
23+
- [Display Parsed Results](#display-parsed-results)
24+
- [Build and Run the Project](#build-and-run-the-project)
25+
26+
## Requirements
27+
28+
- Supported OS: Android 5.0 (API Level 21) or higher.
29+
- Supported ABI: **armeabi-v7a**, **arm64-v8a**, **x86** and **x86_64**.
30+
- Development Environment: Android Studio 3.4+ (Android Studio 4.2+ recommended).
31+
32+
## Add the Libraries
33+
34+
The Dynamsoft Code Parser (DCP) Android SDK comes with four libraries:
35+
36+
| File | Description |
37+
|---------|-------------|
38+
| `DynamsoftCodeParser.aar` | The Dynamsoft Code Parser library, which includes code parsing logic and related APIs. |
39+
| `DynamsoftCore.aar` | The core library, which includes common basic structures and intermediate result related APIs. |
40+
| `DynamsoftLicense.aar` | The license library, which includes license related APIs. |
41+
| `DynamsoftCodeParserDedicator.aar`| The code parser helper library, which includes some validation functions used by the SDK.|
42+
43+
There are two ways to add the libraries into your project - **Manually** and **Maven**.
44+
45+
### Add the Libraries Manually
46+
47+
1. Download the SDK package from the <a href="https://www.dynamsoft.com/survey/dlr/?utm_source=docs" target="_blank">Dynamsoft Website</a>. After unzipping, four **aar** files can be found in the **Dynamsoft\Libs** directory:
48+
49+
- **DynamsoftCodeParser.aar**
50+
- **DynamsoftCore.aar**
51+
- **DynamsoftLicense.aar**
52+
- **DynamsoftCodeParserDedicator.aar**
53+
54+
2. Copy the above seven **aar** files to the target directory such as `[App Project Root Path]\app\libs`
55+
56+
3. Open the file `[App Project Root Path]\app\build.gradle` and add the reference in the dependencies:
57+
58+
```groovy
59+
dependencies {
60+
implementation fileTree(dir: 'libs', include: ['*.aar'])
61+
}
62+
```
63+
64+
4. Click **Sync Now**. After the synchronization is complete, the SDK is added to the project.
65+
66+
### Add the Libraries via Maven
67+
68+
1. Open the file `[App Project Root Path]\app\build.gradle` and add the Maven repository:
69+
70+
```groovy
71+
repositories {
72+
maven {
73+
url "https://download2.dynamsoft.com/maven/aar"
74+
}
75+
}
76+
```
77+
78+
2. Add the references in the dependencies:
79+
80+
```groovy
81+
dependencies {
82+
implementation 'com.dynamsoft:dynamsoftcodeparser:2.0.20'
83+
}
84+
```
85+
86+
3. Click **Sync Now**. After the synchronization is complete, the SDK is added to the project.
87+
88+
## Build Your First Application
89+
90+
In this section, we are going to explain how to create a simple `HelloWorld` app for parsing text or bytes.
91+
92+
>Note:
93+
>
94+
>- Android Studio 2022.3.1 is used here in this guide.
95+
>- You can get similar source code from
96+
> - <a href="https://github.com/Dynamsoft/code-parser-mobile-samples/tree/main/android/HelloWorld" target="_blank">HelloWorld Sample (Java)</a>
97+
98+
### Create a New Project
99+
100+
1. Open Android Studio and select New Project… in the File > New > New Project… menu to create a new project.
101+
102+
2. Choose the correct template for your project. In this sample, we'll use `Empty Activity`.
103+
104+
3. When prompted, choose your app name (`HelloWorld`) and set the Save location, Language, and Minimum SDK (21)
105+
>Note: With minSdkVersion set to 21, your app is available on more than 94.1% of devices on the Google Play Store (last update: March 2021).
106+
107+
### Include the Library
108+
109+
Add the SDK to your new project. Please read [Add the Libraries](#add-the-libraries) section for more details.
110+
111+
### Initialize the License
112+
113+
1. Initialize the license in the file `MainActivity.java`.
114+
115+
```java
116+
import com.dynamsoft.license.LicenseManager;
117+
public class MainActivity extends AppCompatActivity {
118+
@Override
119+
protected void onCreate(Bundle savedInstanceState) {
120+
super.onCreate(savedInstanceState);
121+
setContentView(R.layout.activity_main);
122+
LicenseManager.initLicense("DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9", this, (isSuccess, error) -> {
123+
if (!isSuccess) {
124+
error.printStackTrace();
125+
}
126+
});
127+
}
128+
}
129+
```
130+
131+
>Note:
132+
>
133+
>- The license string here grants a time-limited free trial which requires network connection to work.
134+
>- You can request for a 30-day trial license via the <a href="https://www.dynamsoft.com/customer/license/trialLicense?product=dlr&utm_source=guide&package=android" target="_blank">Customer Portal</a>. Offline trial license is also available by <a href="https://www.dynamsoft.com/contact/" target="_blank">contacting us</a>.
135+
>- If you download the <a href="https://www.dynamsoft.com/survey/dlr/?utm_source=docs" target="_blank">Installation Package</a>, it comes with a 30-day trial license by default.
136+
137+
### Initialize Code Parser And Parse the Code Bytes
138+
139+
1. Import and initialize the `CodeParser`.
140+
141+
```java
142+
import com.dynamsoft.dcp.CodeParser;
143+
public class MainActivity extends AppCompatActivity {
144+
private CodeParser mParser;
145+
@Override
146+
protected void onCreate(Bundle savedInstanceState) {
147+
...
148+
mParser = new CodeParser(this);
149+
}
150+
}
151+
```
152+
153+
2. In the Project window, open **app > res > layout > `activity_main.xml`**, create a "Parse" button control under the root node.
154+
155+
```xml
156+
<Button
157+
android:id="@+id/btn_parse"
158+
android:layout_width="wrap_content"
159+
android:layout_height="wrap_content"
160+
android:layout_marginBottom="50dp"
161+
android:text="Parse"
162+
android:textAllCaps="false"
163+
android:textSize="20sp"
164+
android:backgroundTint="@android:color/holo_blue_dark"
165+
app:layout_constraintBottom_toBottomOf="parent"
166+
app:layout_constraintEnd_toEndOf="parent"
167+
app:layout_constraintStart_toStartOf="parent" />
168+
```
169+
170+
3. Parse the code bytes when the user clicks the "Parse" button. Here we use the passport MRZ string as an example.
171+
172+
```java
173+
public class MainActivity extends AppCompatActivity {
174+
@Override
175+
protected void onCreate(Bundle savedInstanceState) {
176+
...
177+
final String passportMRZStr = "P<D<<ADENAUER<<KONRAD<HERMANN<JOSEPH<<<<<<<<1234567897D<<7601059M6704115<<<<<<<<<<<<<<<2";
178+
179+
Button ParseButton = findViewById(R.id.btn_parse);
180+
ParseButton.setOnClickListener(new View.OnClickListener() {
181+
@Override
182+
public void onClick(View view) {
183+
new Thread(() -> parseCode(passportMRZStr.getBytes())).start();
184+
}
185+
});
186+
}
187+
188+
private void parseCode(byte[] codeBytes) {
189+
try {
190+
ParsedResultItem parsedResultItem = mParser.parse(codeBytes, "");
191+
showResults(parsedResultItem);
192+
} catch (CodeParserException e) {
193+
e.printStackTrace();
194+
}
195+
}
196+
}
197+
```
198+
199+
### Display Parsed Results
200+
201+
1. Display the parsed result(s) in an alert dialog box.
202+
203+
```java
204+
public class MainActivity extends AppCompatActivity {
205+
...
206+
private void showResults(ParsedResultItem item) {
207+
StringBuilder result = new StringBuilder();
208+
209+
for (HashMap.Entry<String, String> entry : item.getParsedFields().entrySet()) {
210+
String key = entry.getKey();
211+
String value = entry.getValue();
212+
213+
result.append(key).append(":").append(value).append("\n");
214+
}
215+
216+
runOnUiThread(() -> {
217+
new AlertDialog.Builder(this)
218+
.setTitle("Result")
219+
.setMessage(result.toString())
220+
.setPositiveButton("OK", null)
221+
.setCancelable(true)
222+
.show();
223+
});
224+
}
225+
}
226+
```
227+
228+
### Build and Run the Project
229+
230+
1. Select the device that you want to run your app on from the target device drop-down menu in the toolbar.
231+
232+
2. Click the **Run app** button, then Android Studio installs your app on the connected device and launches it.
233+
234+
You can also download the full source code of all the steps above:
235+
236+
- <a href="https://github.com/Dynamsoft/code-parser-mobile-samples/tree/main/android/HelloWorld" target="_blank">HelloWorld Sample (Java)</a>

0 commit comments

Comments
 (0)