context-mod/docs/activitiesWindow.md

Activity Window

Most Rules have a window property somewhere within their configuration. This property defines the range of Activities (submission and/or comments) that should be retrieved for checking the criteria of the Rule.

As an example if you want to run an Recent Activity Rule to check if a user has had activity in /r/mealtimevideos you also need to define what range of activities you want to look at from that user's history.

window property overview (tldr)

The value of window can be any of these types:

• number count of activities
• string duration or iso 8601
• duration object
• ActivityWindowCriteria object

Examples of all of the above

// count, last 100 activities
{
  "window": 100
}

// duration string, last 10 days
{
  "window": "10 days"
}

// duration object, last 2 months and 5 days
{
  "window": {
    "months": 2,
    "days": 5,
  }
}

// iso 8601 string, last 15 minutes
{
  "window": "PT15M"
}

// ActivityWindowCriteria, last 100 activities or 6 weeks of activities (whichever is found first)
{
  "window": {
    "count": 100,
    "duration": "6 weeks"
  }
}

Types of Ranges

There are two types of values that can be used when defining a range:

Count

This is the number of activities you want to retrieve. It's straightforward -- if you want to look at the last 100 activities for a user you can use 100 as the value.

Duration

A duration of time between which all activities will be retrieved. This is a relative value that calculates the actual range based on the duration of time subtracted from when the rule is run.

For example:

• Today is July 15th
• You define a duration of 10 days

Then the range of activities to be retrieved will be between July 5th and July 15th (10 days).

Duration Values

The value used to define the duration can be any of these three types:

Duration String (recommended)

A string consisting of

• A Dayjs unit of time
• The value of that unit of time

Examples:

• 9 days
• 14 hours
• 80 seconds

You can ensure your string is valid by testing it here.

Duration Object

If you need to specify multiple units of time for your duration you can instead provide a Dayjs duration object consisting of Dayjs unit-values.

Example

{
  "days": 4,
  "hours": 6,
  "minutes": 20
}

An ISO 8601 duration string

If you're a real nerd you can also use a standard duration) string.

Examples

• PT15M (15 minutes)

Ensure your string is valid by testing it here.

ActivityWindowCriteria

This is an object that lets you specify more granular conditions for your range.

The full object looks like this:

{
  "count": 100,
  "duration": "10 days",
  "satisfyOn": "any",
  "subreddits": {
    "include": ["mealtimevideos","pooptimevideos"],
    "exclude": ["videos"]
  }
}

Specifying Range

You may use one or both range properties.

If both range properties are specified then the value satisfyOn determines how the final range is determined

Using "satisfyOn": "any" (default)

If any then Activities will be retrieved until one of the range properties is met, whichever occurs first.

Example

{
  "count": 80,
  "duration": "90 days",
  "satisfyOn": "any"
}

Activities are retrieved in chunks of 100 (or count, whichever is smaller)

• If 90 days of activities returns only 40 activities => returns 40 activities
• If 80 activities is only 20 days of range => 80 activities

Using "satisfyOn": "all"

If all then both ranges must be satisfied. Effectively, whichever range produces the most Activities will be the one that is used.

Example

{
  "count": 100,
  "duration": "90 days",
  "satisfyOn": "all"
}

Activities are retrieved in chunks of 100 (or count, whichever is smaller)

• If at 90 days of activities => 40 activities retrieved
  • continue retrieving results until 100 activities
  • so range is >90 days of activities
• If at 100 activities => 20 days of activities retrieved
  • continue retrieving results until 90 days of range
  • so results in >100 activities

Filtering Activities

You may filter retrieved Activities using an array of subreddits.

Note: Activities are filtered before range check is made so you will always end up with specified range (but may require more api calls if many activities are filtered out)

Include

Use include to specify which subreddits should be included from results

Example where only activities from /r/mealtimevideos and /r/modsupport will be returned

{
  "count": 100,
  "duration": "90 days",
  "satisfyOn": "any",
  "subreddits": {
    "include": ["mealtimevideos","modsupport"]
  }
}

Exclude

Use exclude to specify which subreddits should NOT be in the results

Example where activities from /r/mealtimevideos and /r/modsupport will not be returned in results

{
  "count": 100,
  "duration": "90 days",
  "satisfyOn": "any",
  "subreddits": {
    "exclude": ["mealtimevideos","modsupport"]
  }
}

Note: exclude will be ignored if include is also present.