Skip to content

Commit 50e4ac1

Browse files
rlepinskirlepinski
authored
Add migration guide and kdoc for templates (#1978)
1 parent 8175db5 commit 50e4ac1

File tree

5 files changed

+332
-0
lines changed

5 files changed

+332
-0
lines changed

‎documentation/migration/migration-guide-19-20.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ The Airship SDK 20.0 introduces major architectural changes including the renami
2626
- [Minor Push Notification Changes](#minor-push-notification-changes)
2727
- [Permissions Manager API Changes](#permissions-manager-api-changes)
2828
- [Action Framework Changes](#action-framework-changes)
29+
- [Event Template Changes](#event-template-changes)
2930
- [Deprecated APIs](#deprecated-apis)
3031
- [UAirship Deprecated](#uairship-deprecated)
3132
- [Autopilot Signature Change](#autopilot-signature-change)
@@ -242,6 +243,197 @@ Airship.actionRegistry.registerEntry(setOf("my_action")) {
242243
}
243244
```
244245

246+
### Event Template Changes
247+
248+
The event template classes (`RetailEventTemplate`, `MediaEventTemplate`, `AccountEventTemplate`, `SearchEventTemplate`) have been redesigned. The old template classes that combined properties and event creation have been replaced with a new architecture that separates concerns into `Type` and `Properties` classes, with event creation handled by `CustomEvent`.
249+
250+
#### Package Change
251+
252+
All event templates have moved to a new package:
253+
254+
| SDK 19.x | SDK 20.x |
255+
|---|---|
256+
| `com.urbanairship.analytics.RetailEventTemplate` | `com.urbanairship.analytics.templates.RetailEventTemplate` |
257+
| `com.urbanairship.analytics.MediaEventTemplate` | `com.urbanairship.analytics.templates.MediaEventTemplate` |
258+
| `com.urbanairship.analytics.AccountEventTemplate` | `com.urbanairship.analytics.templates.AccountEventTemplate` |
259+
| `com.urbanairship.analytics.SearchEventTemplate` | `com.urbanairship.analytics.templates.SearchEventTemplate` |
260+
261+
#### API Changes
262+
263+
In SDK 19.x, templates were created via factory methods, properties were set directly on the template, and events were created from the template. In SDK 20.x, this is split into:
264+
265+
1. **`Type`** — a sealed class (or enum) that defines the event situation (e.g., `Purchased`, `AddedToCart`)
266+
2. **`Properties`** — a data class holding template-specific fields (e.g., category, brand, description)
267+
3. **`CustomEvent.newBuilder(type, properties)`** — creates the event, with event-level fields like `eventValue` and `transactionId` set on the builder
268+
269+
##### Retail Event Template
270+
271+
| SDK 19.x Factory Method | SDK 20.x Type |
272+
|---|---|
273+
| `RetailEventTemplate.newPurchasedTemplate()` | `RetailEventTemplate.Type.Purchased` |
274+
| `RetailEventTemplate.newAddedToCartTemplate()` | `RetailEventTemplate.Type.AddedToCart` |
275+
| `RetailEventTemplate.newBrowsedTemplate()` | `RetailEventTemplate.Type.Browsed` |
276+
| `RetailEventTemplate.newStarredProductTemplate()` | `RetailEventTemplate.Type.Starred` |
277+
| `RetailEventTemplate.newSharedTemplate(source, medium)` | `RetailEventTemplate.Type.Shared(source, medium)` |
278+
| `RetailEventTemplate.newWishlistTemplate(id, name)` | `RetailEventTemplate.Type.Wishlist(id, name)` |
279+
280+
| SDK 19.x Template Method | SDK 20.x Location |
281+
|---|---|
282+
| `template.setCategory(...)` | `RetailEventTemplate.Properties(category = ...)` |
283+
| `template.setId(...)` | `RetailEventTemplate.Properties(id = ...)` |
284+
| `template.setDescription(...)` | `RetailEventTemplate.Properties(eventDescription = ...)` |
285+
| `template.setBrand(...)` | `RetailEventTemplate.Properties(brand = ...)` |
286+
| `template.setValue(...)` | `CustomEvent.Builder.setEventValue(...)` |
287+
| `template.setTransactionId(...)` | `CustomEvent.Builder.setTransactionId(...)` |
288+
| `template.createEvent()` | `CustomEvent.newBuilder(type, properties).build()` |
289+
290+
###### Java
291+
```java
292+
// SDK 19.x
293+
RetailEventTemplate template = RetailEventTemplate.newPurchasedTemplate();
294+
template.setCategory("shoes")
295+
.setId("sku-123")
296+
.setDescription("Running Shoes")
297+
.setBrand("Nike")
298+
.setValue(99.99)
299+
.setTransactionId("txn-456")
300+
.createEvent()
301+
.track();
302+
303+
// SDK 20.x
304+
RetailEventTemplate.Properties properties = RetailEventTemplate.Properties.newBuilder()
305+
.setId("sku-123")
306+
.setCategory("shoes")
307+
.setDescription("Running Shoes")
308+
.setBrand("Nike")
309+
.build();
310+
311+
CustomEvent.newBuilder(RetailEventTemplate.Type.Purchased, properties)
312+
.setEventValue(99.99)
313+
.setTransactionId("txn-456")
314+
.build()
315+
.track();
316+
```
317+
318+
###### Kotlin
319+
```kotlin
320+
// SDK 19.x
321+
RetailEventTemplate.newPurchasedTemplate()
322+
.setCategory("shoes")
323+
.setId("sku-123")
324+
.setDescription("Running Shoes")
325+
.setBrand("Nike")
326+
.setValue(99.99)
327+
.setTransactionId("txn-456")
328+
.createEvent()
329+
.track()
330+
331+
// SDK 20.x
332+
customEvent(
333+
RetailEventTemplate.Type.Purchased,
334+
RetailEventTemplate.Properties(
335+
id = "sku-123",
336+
category = "shoes",
337+
eventDescription = "Running Shoes",
338+
brand = "Nike"
339+
)
340+
) {
341+
setEventValue(99.99)
342+
setTransactionId("txn-456")
343+
}.track()
344+
```
345+
346+
##### Media Event Template
347+
348+
| SDK 19.x Factory Method | SDK 20.x Type |
349+
|---|---|
350+
| `MediaEventTemplate.newBrowsedTemplate()` | `MediaEventTemplate.Type.Browsed` |
351+
| `MediaEventTemplate.newConsumedTemplate()` | `MediaEventTemplate.Type.Consumed` |
352+
| `MediaEventTemplate.newStarredTemplate()` | `MediaEventTemplate.Type.Starred` |
353+
| `MediaEventTemplate.newSharedTemplate(source, medium)` | `MediaEventTemplate.Type.Shared(source, medium)` |
354+
355+
###### Kotlin
356+
```kotlin
357+
// SDK 19.x
358+
MediaEventTemplate.newConsumedTemplate()
359+
.setCategory("podcasts")
360+
.setId("episode-123")
361+
.setDescription("Tech Talk #42")
362+
.setAuthor("Jane Doe")
363+
.setValue(1.0)
364+
.createEvent()
365+
.track()
366+
367+
// SDK 20.x
368+
customEvent(
369+
MediaEventTemplate.Type.Consumed,
370+
MediaEventTemplate.Properties(
371+
id = "episode-123",
372+
category = "podcasts",
373+
eventDescription = "Tech Talk #42",
374+
author = "Jane Doe"
375+
)
376+
) {
377+
setEventValue(1.0)
378+
}.track()
379+
```
380+
381+
##### Account Event Template
382+
383+
| SDK 19.x Factory Method | SDK 20.x Type |
384+
|---|---|
385+
| `AccountEventTemplate.newRegisteredTemplate()` | `AccountEventTemplate.Type.REGISTERED` |
386+
| `AccountEventTemplate.newLoggedInTemplate()` | `AccountEventTemplate.Type.LOGGED_IN` |
387+
| `AccountEventTemplate.newLoggedOutTemplate()` | `AccountEventTemplate.Type.LOGGED_OUT` |
388+
389+
###### Kotlin
390+
```kotlin
391+
// SDK 19.x
392+
AccountEventTemplate.newRegisteredTemplate()
393+
.setCategory("premium")
394+
.setValue(9.99)
395+
.createEvent()
396+
.track()
397+
398+
// SDK 20.x
399+
customEvent(
400+
AccountEventTemplate.Type.REGISTERED,
401+
AccountEventTemplate.Properties(category = "premium")
402+
) {
403+
setEventValue(9.99)
404+
}.track()
405+
```
406+
407+
##### Search Event Template
408+
409+
| SDK 19.x Factory Method | SDK 20.x Type |
410+
|---|---|
411+
| `SearchEventTemplate.newSearchTemplate()` | `SearchEventTemplate.Type.SEARCH` |
412+
413+
###### Kotlin
414+
```kotlin
415+
// SDK 19.x
416+
SearchEventTemplate.newSearchTemplate()
417+
.setCategory("hotels")
418+
.setQuery("beach resort")
419+
.setTotalResults(53)
420+
.setValue(1.0)
421+
.createEvent()
422+
.track()
423+
424+
// SDK 20.x
425+
customEvent(
426+
SearchEventTemplate.Type.SEARCH,
427+
SearchEventTemplate.Properties(
428+
category = "hotels",
429+
query = "beach resort",
430+
totalResults = 53
431+
)
432+
) {
433+
setEventValue(1.0)
434+
}.track()
435+
```
436+
245437
## Deprecated APIs
246438

247439
### UAirship Deprecated

‎urbanairship-core/src/main/java/com/urbanairship/analytics/templates/AccountEventTemplate.kt‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,35 @@ import com.urbanairship.json.JsonSerializable
66
import com.urbanairship.json.JsonValue
77
import com.urbanairship.json.jsonMapOf
88

9+
/**
10+
* Account event template. Use with [com.urbanairship.analytics.CustomEvent.newBuilder]
11+
* or [com.urbanairship.analytics.customEvent] to create a custom event with account template properties.
12+
*
13+
* Example (Kotlin):
14+
* ```
15+
* customEvent(
16+
* AccountEventTemplate.Type.REGISTERED,
17+
* AccountEventTemplate.Properties(category = "premium")
18+
* ) {
19+
* setEventValue(9.99)
20+
* }.track()
21+
* ```
22+
*
23+
* Example (Java):
24+
* ```
25+
* AccountEventTemplate.Properties properties = AccountEventTemplate.Properties.newBuilder()
26+
* .setCategory("premium")
27+
* .build();
28+
*
29+
* CustomEvent.newBuilder(AccountEventTemplate.Type.REGISTERED, properties)
30+
* .setEventValue(9.99)
31+
* .build()
32+
* .track();
33+
* ```
34+
*
35+
* @see com.urbanairship.analytics.CustomEvent.newBuilder
36+
* @see com.urbanairship.analytics.customEvent
37+
*/
938
public sealed class AccountEventTemplate {
1039

1140
public enum class Type(internal val eventName: String) {

‎urbanairship-core/src/main/java/com/urbanairship/analytics/templates/MediaEventTemplate.kt‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,43 @@ import com.urbanairship.json.JsonSerializable
66
import com.urbanairship.json.JsonValue
77
import com.urbanairship.json.jsonMapOf
88

9+
/**
10+
* Media event template. Use with [com.urbanairship.analytics.CustomEvent.newBuilder]
11+
* or [com.urbanairship.analytics.customEvent] to create a custom event with media template properties.
12+
*
13+
* Example (Kotlin):
14+
* ```
15+
* customEvent(
16+
* MediaEventTemplate.Type.Consumed,
17+
* MediaEventTemplate.Properties(
18+
* id = "episode-123",
19+
* category = "podcasts",
20+
* eventDescription = "Tech Talk #42",
21+
* author = "Jane Doe"
22+
* )
23+
* ) {
24+
* setEventValue(1.0)
25+
* }.track()
26+
* ```
27+
*
28+
* Example (Java):
29+
* ```
30+
* MediaEventTemplate.Properties properties = MediaEventTemplate.Properties.newBuilder()
31+
* .setId("episode-123")
32+
* .setCategory("podcasts")
33+
* .setDescription("Tech Talk #42")
34+
* .setAuthor("Jane Doe")
35+
* .build();
36+
*
37+
* CustomEvent.newBuilder(MediaEventTemplate.Type.Consumed, properties)
38+
* .setEventValue(1.0)
39+
* .build()
40+
* .track();
41+
* ```
42+
*
43+
* @see com.urbanairship.analytics.CustomEvent.newBuilder
44+
* @see com.urbanairship.analytics.customEvent
45+
*/
946
public sealed class MediaEventTemplate {
1047

1148
public sealed class Type(internal val eventName: String) {

‎urbanairship-core/src/main/java/com/urbanairship/analytics/templates/RetailEventTemplate.kt‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,45 @@ import com.urbanairship.json.JsonSerializable
66
import com.urbanairship.json.JsonValue
77
import com.urbanairship.json.jsonMapOf
88

9+
/**
10+
* Retail event template. Use with [com.urbanairship.analytics.CustomEvent.newBuilder]
11+
* or [com.urbanairship.analytics.customEvent] to create a custom event with retail template properties.
12+
*
13+
* Example (Kotlin):
14+
* ```
15+
* customEvent(
16+
* RetailEventTemplate.Type.Purchased,
17+
* RetailEventTemplate.Properties(
18+
* id = "sku-123",
19+
* category = "shoes",
20+
* eventDescription = "Running Shoes",
21+
* brand = "Nike"
22+
* )
23+
* ) {
24+
* setEventValue(99.99)
25+
* setTransactionId("txn-456")
26+
* }.track()
27+
* ```
28+
*
29+
* Example (Java):
30+
* ```
31+
* RetailEventTemplate.Properties properties = RetailEventTemplate.Properties.newBuilder()
32+
* .setId("sku-123")
33+
* .setCategory("shoes")
34+
* .setDescription("Running Shoes")
35+
* .setBrand("Nike")
36+
* .build();
37+
*
38+
* CustomEvent.newBuilder(RetailEventTemplate.Type.Purchased, properties)
39+
* .setEventValue(99.99)
40+
* .setTransactionId("txn-456")
41+
* .build()
42+
* .track();
43+
* ```
44+
*
45+
* @see com.urbanairship.analytics.CustomEvent.newBuilder
46+
* @see com.urbanairship.analytics.customEvent
47+
*/
948
public sealed class RetailEventTemplate {
1049

1150
public sealed class Type(internal val eventName: String) {

‎urbanairship-core/src/main/java/com/urbanairship/analytics/templates/SearchEventTemplate.kt‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,41 @@ import com.urbanairship.json.JsonSerializable
66
import com.urbanairship.json.JsonValue
77
import com.urbanairship.json.jsonMapOf
88

9+
/**
10+
* Search event template. Use with [com.urbanairship.analytics.CustomEvent.newBuilder]
11+
* or [com.urbanairship.analytics.customEvent] to create a custom event with search template properties.
12+
*
13+
* Example (Kotlin):
14+
* ```
15+
* customEvent(
16+
* SearchEventTemplate.Type.SEARCH,
17+
* SearchEventTemplate.Properties(
18+
* category = "hotels",
19+
* query = "beach resort",
20+
* totalResults = 53
21+
* )
22+
* ) {
23+
* setEventValue(1.0)
24+
* }.track()
25+
* ```
26+
*
27+
* Example (Java):
28+
* ```
29+
* SearchEventTemplate.Properties properties = SearchEventTemplate.Properties.newBuilder()
30+
* .setCategory("hotels")
31+
* .setQuery("beach resort")
32+
* .setTotalResults(53)
33+
* .build();
34+
*
35+
* CustomEvent.newBuilder(SearchEventTemplate.Type.SEARCH, properties)
36+
* .setEventValue(1.0)
37+
* .build()
38+
* .track();
39+
* ```
40+
*
41+
* @see com.urbanairship.analytics.CustomEvent.newBuilder
42+
* @see com.urbanairship.analytics.customEvent
43+
*/
944
public sealed class SearchEventTemplate {
1045

1146
public enum class Type(internal val eventName: String) {

0 commit comments

Comments
 (0)