Adobe R Packages Update

class: center, middle, inverse, title-slide

# Adobe R Packages Update
### Ben Woodard
### Search Discovery
### 2022-04-01 (updated: 2022-05-28)

---

---
class: maintitle
# Building Segments

---
class: subsection
# New Function Introduction Junction

---
class: titlebody
# Verbs

This data function will return a list of all available verbs for building segments. They are divided up into 3 different categories: 'Exists', 'Strings', and 'Numbers'. You can determine what category of verb to use by the object you are going to be using. For instance, if the object is going to be a number then the verb must be a number verb.  
```
seg_verbs
```

|type   |class  |verb                |description                                                                                                                                                     |
|:------|:------|:-------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------|
|string |string |streq               |Equals                                                                                                                                                          |
|string |string |not-streq           |Not Equals                                                                                                                                                      |
|string |string |strlt               |Less Than                                                                                                                                                       |
|string |string |strgt               |Greater Than                                                                                                                                                    |
|string |string |strle               |Less Than or Equals                                                                                                                                             |
|string |string |strge               |Greater Than or Equals                                                                                                                                          |
|string |list   |streq-in            |Match a string to any of the values in the parameter                                                                                                            |
|string |list   |not-streq-in        |Ensure a string doesn't match any of the values in the parameter                                                                                                |
|string |string |contains            |Ensure a string matches or contains the value in the parameter                                                                                                  |
|string |string |not-contains        |Ensure a string doesn't match or contains the value in the parameter                                                                                            |
|string |list   |contains-any-of     |Ensure a string contains any of the values in the parameter. Case-insensitive.                                                                                  |
|string |list   |contains-all-of     |Ensure a string contains all of the values in the parameter. Case-insensitive.                                                                                  |
|string |list   |not-contains-any-of |Ensure a string doesn't contain at least one of the values in the parameter. Case-insensitive.                                                                  |
|string |list   |not-contains-all-of |Ensure a string doesn't contain any of the values in the parameter. Case-insensitive.                                                                           |
|string |string |starts-with         |Ensure a string starts with the value in the parameter. Case-insensitive.                                                                                       |
|string |string |ends-with           |Ensure a string ends with the value in the parameter. Case-insensitive.                                                                                         |
|string |string |not-starts-with     |Ensure a string doesn't start with the value in the parameter. Case-insensitive.                                                                                |
|string |string |not-ends-with       |Ensure a string doesn't end with the value in the parameter. Case-insensitive.                                                                                  |
|string |glob   |matches             |Ensure a string matches the glob parameter. A glob parameter uses a '' character to match any sequence of characters. A literal '' is expressed with '*'.       |
|string |glob   |not-matches         |Ensure a string doesn't match the glob parameter. A glob parameter uses a '' character to match any sequence of characters. A literal '' is expressed with '*'. |
|number |number |eq                  |Equals                                                                                                                                                          |
|number |number |not-eq              |Not equals                                                                                                                                                      |
|number |number |gt                  |Greater than                                                                                                                                                    |
|number |number |lt                  |Less than                                                                                                                                                       |
|number |number |ge                  |Greater than or equal to                                                                                                                                        |
|number |number |le                  |Less than                                                                                                                                                       |
|number |list   |eq-any-of           |Equal to any of the values provided                                                                                                                             |
|number |list   |not-eq-any-of       |Not equal to any of the values provided                                                                                                                         |
|number |list   |eq-in               |Equal to any of the values provided                                                                                                                             |
|number |list   |not-eq-in           |Not equal to any of the values provided                                                                                                                         |
|string |exists |exists              |Tests if an attribute has been set to a value.                                                                                                                  |
|string |exists |not-exists          |Tests if an attribute has never been set to a value.                                                                                                            |
|number |exists |event-exists        |Tests if an attribute has been set to a number value.                                                                                                           |
|number |exists |not-event-exists    |Tests if an attribute has never been set to a number value.                                                                                                     |

---
class: titlebody
# New Functions

1. `seg_rule()` - This function creates the simple rule of a segment.

`seg_rule(dimension, metric, verb, object)`
    
2. `seg_then()` - This function creates a then list object which restricts the time constraint of a segment to be added to a sequence segment.

`seg_then(limit = "within", count = 1, unit = "year")`
      
3. `seg_con()` - This function combines rules into a container.

`seg_con(context = "hits", conjunction = "and", rules = NULL, exclude = FALSE)`

4. `seg_seq()` - This function combines rules into a sequence container.
  
    `seg_seq(context = "visits", rules = NULL, sequence = "in_order")`

5. `seg_build()` - This function combines rules, containers and/or sequences into a single JSON string and can then make the post call to create the segment in Adobe Analytics or return the json string for use in other api calls or for validation.

`seg_build(name, description, rules, context = "hits", conjunction = "and", create_seg = FALSE)`

6. `seg_val()` - Returns a segment validation response for a segment contained in a json string object.

`seg_val(segment_body)`

---
class: titlebody
# Basic Segment Example

```r
rule1 = seg_rule(dimension = 'daterangehour', 
                 verb = 'eq', 
                 object = c('2021-11-02', '1600'))
rule2 = seg_rule(dimension = 'page', 
                 verb = 'contains', 
                 object = 'home')
built <- seg_build('Basic Segment For My Test',
                   'This was created by Ben Woodard as a test',
                   conjunction = 'and',
                   rules = list(rule1, rule2),
                   context = 'visitors')
seg_val(built)
```

```
## [1] "The segment is valid."
```

---
class: titlebody
# Adding containers to build the segment

```r
rule1 = seg_rule(dimension = 'daterangehour', 
                 verb = 'eq', 
                 object = c('2021-11-02', '1600'))
rule2 = seg_rule(dimension = 'page', 
                 verb = 'contains', 
                 object = 'home', 
                 description = 'something')
rule3 = seg_rule(metric = 'visits', 
                 verb = 'exists')
con1 = seg_con(context = 'hits',
               conjunction = 'or',
               rules = list(seg_rule(dimension = 'page', 
                 verb = 'contains', 
                 object = 'home', 
                 description = 'something'), rule3))
built <- seg_build('This is a Basic combined Segment For My Test',
                   'This was created by Ben Woodard as a test',
                   conjunction = 'and',
                   containers = list(rule1, con1),
                   context = 'visits',
                   create_seg = F)
seg_val(built)
```

---
class: titlebody
# Non-repeating Instance and Repeating Instance

```r
rule1 <- seg_rule(dimension = 'page', 
                  verb = 'streq', 
                  object = 'Home', 
                  attribution = 'repeating') #default
rule2 <- seg_rule(dimension = 'page', 
                  verb = 'streq', 
                  object = 'Home', 
                  attribution = 'nonrepeating', 
                  attribution_context = 'visits')
rule3 <- seg_rule(dimension = 'visitnumber', 
                  verb = 'eq', 
                  object = 1, 
                  attribution = 'instance')
built <- seg_build(name = 'Instance and Non-Repeating Instance example',
          description = 'This is the example of the repeating and non-repeating instance',
          rules = list(rule1, rule2, rule3), 
          context = 'hits',
          conjunction = 'or',
          create_seg = F)
seg_val(built)
```

---
class: titlebody
# Count Distinct Dimension Segment

```r
rule1 <- seg_rule(dimension = 'page',
                  is_distinct = TRUE,
                  verb = 'ge', #using number verb because the count distinct argument is true
                  object = 5)
built <- seg_build(name = "Count Distinct Segment",
                   description = "Unique Counts",
                   context = 'visitors',
                   rules = list(rule1) )
seg_val(built)
```

---
class: titlebody
# Excluding Containers in a segment

```r
#create the rule to define the page view
rule <- seg_rule(dimension = 'page',
                      verb = 'streq',
                      object = 'Home')
#create the 2 page view limite per visitor
con2 <- seg_seq(context = 'visitors',
                rules = list(rule, rule), 
                sequence = 'in_order') #this uses the conjunction 'then'
#create the container including either visitors with 1 or 2 pageviews
con2_in <- seg_con(context = 'visitors',
                   conjunction = 'or',
                   rules = list(rule, con2))
#create the container exclude visitors with 3 pageviews (would automatically exclude more than 3 because they had 3 if they had 4.)
con3_x <- seg_seq(context = 'visitors', 
                  rules = list(rule, rule, rule), 
                  sequence = 'in_order',
                  exclude = TRUE) 
#create the segment in Adobe 
built <- seg_build(name = "Exclude 2 Home Pageview Visitors",
                   description = "Written as an example",
                   context = 'visitors',
                   rules = list(con2_in, con3_x), 
                   conjunction = 'and')
seg_val(built)
```

---
class: subsection
# Sequence Segments

---
class: titlebody
# Basic Sequence

```r
rule1 <- seg_rule(dimension = 'daterangeday',
                  verb = 'eq',
                  object = '2021-09-13')

rule2 <- seg_rule(dimension = 'page',
                  verb = 'contains',
                  object = 'blog')

built <- seg_build('Visited on 9/13 and then visited the blog',
                     'This was created by Ben Woodard as a test',
                     sequences = list(rule1, rule2),
                     sequence = 'in_order',
                     context = 'visitors')

seg_val(built)
```

---
class: titlebody
# Basic Context Change Sequence

```r
rule1 <- seg_rule(dimension = 'daterangeday',
                  verb = 'eq',
                  object = '2021-09-13')
then <- seg_then(limit = 'after', count = 2, unit = 'hit')
rule2 <- seg_rule(dimension = 'page',
                  verb = 'contains',
                  object = 'blog')
built <- seg_build('Visited on 9/13 and then after 2 hits visited the blog',
                   'This was created by Ben Woodard as a test',
                   sequences = list(rule1, then, rule2),
                   sequence_context = 'visits', 
                   sequence = 'in_order',
                   context = 'visitors')
seg_val(built)
```

---
class: titlebody
# Time Restriction (then) Sequence

Adding a time restriction using the `seg_then()` function

In the UI there is a clock after the "then" term. when clicked there are 2 options that are shown: `after` and `while`.

```r
rule1 <- seg_rule(dimension = 'daterangeday',
         verb = 'eq',
         object = '2021-09-13')
thenit <- seg_then('after', 1, 'hit')

rule2 <- seg_rule(dimension = 'page',
                  verb = 'contains',
                  object = 'blog')
sequ <- seg_seq(context = 'visits', 
                rules = list(rule1, thenit, rule2))
built <- seg_build('Visited on 9/13 and then visited the blog',
                   'This was created by Ben Woodard as a test',
                   containers = list(sequ),
                   context = 'visits',
                   sequence_context = 'visitors')
seg_val(built)
```

---
class: titlebody
# Within + After Time Restriction Sequence

You can also add the 'after' and 'within' time restrictions together just like in the UI.  The function will automatically put the proper one first but you still want to be cognizant of the time restriction you are placing on your function.

```r
red1 <- seg_rule(dimension = 'daterangeday',
                 verb = 'eq',
                 object = '2021-09-13')
thenit <- seg_then(limit = c('within', 'after'), 
                  count = c(1, 2),
                  unit = c('week', 'visit')) #unit is always singular
rule2 <- seg_rule(dimension = 'page',
                  verb = 'exists')
sequ <- seg_seq(context = 'visits', 
                rules = list(red1, thenit, rule2))
built <- seg_build('Compound then statement',
                     'This was created by Ben Woodard as a test',
                     containers = list(sequ),
                     context = 'visitors')
seg_val(built)
```

---
class: titlebody
# Within + After Time Restriction & Standard Container

This segment will combine the sequence container and basic container into a segment.
.col-md-6[

```r
rule1 <- seg_rule(dimension = 'page',
                 verb = 'streq',
                 object = 'Home')
thenit <- seg_then(limit = c('after', 'within'), 
                  count = c(1, 1),
                  unit = c('hit', 'visit')) #unit is always singular
rule2 <- seg_rule(dimension = 'page',
                  verb = 'contains',
                  object = 'Blog')
rule3 <- seg_rule(dimension = 'visitnumber',
                  verb = 'eq',
                  object = 4)
rule4 <- seg_rule(dimension = 'page',
                  verb = 'exists')
```
]
.col-md-6[

```r
## make the different containers (sequence container and basic container)
sequ1 <- seg_seq(context = 'visits', 
                 rules = list(rule1, thenit, rule2, rule1))
con2 <- seg_con(context = 'hits', 
                rules = list(rule3, rule4))
built <- seg_build(name = 'Compound then statement',
                   description = 'This was created by Ben Woodard as a test',
                   context = 'visitors',
                   sequence_context = 'visits',
                   sequences  = list(sequ1, con2))
seg_val(built)
```
]

---
class: titlebody
# Inline Segment Building

```r
## The basic flow of these objects can be looked at in this way.
built <- seg_build(name = 'Compound then statement',
                   description = 'This was created by Ben Woodard as a test',
                   context = 'visitors',
                   sequence_context = 'visits',
                   sequences  = list(seg_seq(context = 'visits', 
                                             rules = list(seg_rule(dimension = 'page',verb = 'streq',object = 'Home'), 
                                                               seg_then(limit = c('after', 'within'), count = c(1, 1), unit = c('hit', 'visit')), 
                                                               seg_rule(dimension = 'page', verb = 'contains', object = 'Blog'), 
                                                               seg_rule(dimension = 'page',verb = 'streq',object = 'Home'))), 
                                     seg_con(context = 'hits', 
                                             rules = list(seg_rule(dimension = 'visitnumber', verb = 'eq', object = 4), 
                                                                seg_rule(dimension = 'page', verb = 'exists')))) )
```

---
class: titlebody
# In Order, Before, and After Sequence

Sequence prefix and suffix will enable the user to define if the segment should only include those after or before the sequence of events.
.col-md-6[

```r
## make the different containers (sequence container and basic container)
sequ1 <- seg_seq(context = 'visitors', 
                rules = list(rule1, thenit, rule2),
                sequence = 'before') ## adding the sequence to include only visitors before
con2 <- seg_con(context = 'hits', 
                rules = list(rule3, rule4))
built <- seg_build('Using the sequence Before',
                     'This was created by Ben Woodard as a test',
                     sequences  = list(sequ1, con2),
                     sequence_context = 'visits',
                     sequence = 'after', ##Include only those visits after the sequence
                     context = 'visitors')
seg_val(built)
```
]
---
class: titlebody
# Exclude checkpoints in a sequence

```r
rule1 <- seg_rule(dimension = 'page',
                  verb = 'streq',
                  object = 'Home')
rule2 <- seg_rule(dimension = 'page',
                  verb = 'contains',
                  object = 'blog')
rule3 <- seg_rule(dimension = 'visitnumber',
                  verb = 'gt',
                  object = 3)
seq1 <- seg_seq(context = 'visits',
                rules = list(rule1, rule2, rule3),
                sequence = 'in_order',
                exclude = F,
                exclude_checkpoint = 2)
built <- seg_build(name = 'Exclude a checkpoint in a sequence',
                   description = 'defined checkpoint 2 to be excluded from the sequence',
                   containers = list(seq1), 
                   context = 'visits')
seg_val(built)
```