Add Edge event reference by timkimadobe · Pull Request #44 · adobe/aepsdk-edge-android

timkimadobe · 2023-02-04T01:59:07Z

Description

This PR adds the event reference page for the Edge Network extension:

Events handled
Events dispatched
Basically outlining the event contract for all events edge interacts with via the Event Hub

Related Issue

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

I have signed the Adobe Open Source CLA.
My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have read the CONTRIBUTING document.
I have added tests to cover my changes.
All new and existing tests passed.

WIP events dispatched

…/aepsdk-edge-android into edge-event-reference

codecov · 2023-02-10T00:48:52Z

Codecov Report

Merging #44 (a144253) into dev-v2.0.1 (66eac87) will not change coverage.
The diff coverage is n/a.

❗ Current head a144253 differs from pull request most recent head 2288b58. Consider uploading reports for the commit 2288b58 to get more accurate results

@@              Coverage Diff              @@
##             dev-v2.0.1      #44   +/-   ##
=============================================
  Coverage         83.28%   83.28%           
  Complexity          367      367           
=============================================
  Files                29       29           
  Lines              1555     1555           
  Branches            219      219           
=============================================
  Hits               1295     1295           
  Misses              161      161           
  Partials             99       99

Flag	Coverage Δ
functional-tests	`65.85% <ø> (ø)`
unit-tests	`79.16% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

addb · 2023-02-15T19:03:10Z

Documentation/event-reference.md

+#### Event Details<!-- omit in toc -->
+
+| Event type                 | Event source                         |
+| -------------------------- | ------------------------------------ |


We can remove this table since the next table L32 has the same info with the API.

Thanks for catching that! Removed table

Documentation/event-reference.md

Fix event source value

timkimadobe

Thank you for the review @addb! Updated based on feedback

timkimadobe · 2023-02-15T19:37:14Z

Documentation/event-reference.md

+#### Event Details<!-- omit in toc -->
+
+| Event type                 | Event source                         |
+| -------------------------- | ------------------------------------ |


Thanks for catching that! Removed table

Documentation/event-reference.md

addb · 2023-02-15T20:00:52Z

Documentation/event-reference.md

+
+| Key          | Value type    | Required | Description                |
+| ------------ | ------------- | -------- | -------------------------- |
+| locationHint | `boolean`     | Yes      | The Edge Network location hint to use when connecting to Edge Network. Property is set to `true` automatically; it is not user modifiable. |


This field is used to distinguish (edge, requestIdentity) event is a getter for locationHint. Let's update the description accordingly.

We can add Required value as Yes (internal)

That makes sense! Thank you, updated description section

For the Required column what do you think about updating the column name to Key Required or Mandatory Key? Since this doc is from the perspective of Edge extension's own event contract, all of the "Required"-ness should already be implied to be internal right?

Makes sense. We can keep it as is then.

addb · 2023-02-15T20:04:06Z

Documentation/event-reference.md

+
+This event signals that [Identity for Edge Network](https://github.com/adobe/aepsdk-edgeidentity-android) has completed [resetting all identities](https://developer.adobe.com/client-sdks/documentation/identity-for-edge-network/api-reference/#resetidentities) usually following a call to [`MobileCore.resetIdentities()`](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/MobileCore/api-reference.md). 
+
+When this event is received, the Edge extension queues it up and removes the cached internal state:store settings. If other events are queued before this event, these events will be processed first in the order they were received.


... queued before this event, those events...

addb · 2023-02-15T20:05:37Z

Documentation/event-reference.md

+
+This event is a response to the [Edge request identity event](#edge-request-identity)) and provides the location hint being used by the Edge Network extension in requests to the Edge Network. The Edge Network location hint may be used when building the URL for Edge Network requests to hint at the server cluster to use.
+
+| Value | Behavior |


We dont need this consent table here.

We should add this is dispatched for edge-request-identity event with data containing lochint = true

Also add a local href to the section getLocHint

Removed table and added locationHint = true requirement in description

For adding a local href to getLoc Hint, did you mean adding a link to the getLocationHint API in the description for this section? I was thinking the link to Edge request identity event (which has a link to getLocationHint API) would be enough since that API actually creates that event, and not this response one

Documentation/event-reference.md

addb · 2023-02-15T20:12:16Z

Documentation/event-reference.md

+#### Data payload definition<!-- omit in toc -->
+
+| Key       | Value type    | Required | Description           |
+| --------- | ------------- | -------- | --------------------- |


We can add Required value as Yes (internal)

Please see response to: https://github.com/adobe/aepsdk-edge-android/pull/44/files/71da2c1039e2c1a828b918b635e85afcfc53f8bb#r1107661756

addb · 2023-02-15T20:13:15Z

Documentation/event-reference.md

+
+| Event type                        | Event source                          |
+| --------------------------------- | ------------------------------------- |
+| com.adobe.eventType.edge          | This value is copied from the event being responded to; if not set or `null`, has a default value of com.adobe.eventSource.responseContent |


just com.adobe.eventSource.responseContent

I was a bit confused for this one, since the dispatchResponse API is able to generate many different kinds of response events; for this section of "Edge event response" do we only want strictly the
Event type: com.adobe.eventType.edge and Event source: com.adobe.eventSource.responseContent and cover the other potential cases separately in other new sections?

for example dispatchResponse is able to use any eventSource value:

aepsdk-edge-android/code/edge/src/main/java/com/adobe/marketing/mobile/NetworkResponseHandler.java

Line 394 in 4501cc8

source = eventSource;

We should have error response and responseContent. I am not sure how to accommodate any source. @emdobrin @kevinlind Do we have any a limited number eventSource that we expect or this can be anything and we should not try to document each and every known source?

I've removed the variable event source for now; maybe we can address the variable portion in a followup PR?

Standardize table header formatting for easier find and replace in the future Separate API creating event section Update API signature format to match standard java doc format

timkimadobe

Thanks for the review @addb! Updated based on feedback with a few outstanding questions (attached to relevant feedback comments)

Also, I separated the API column from the table in the cases where the APIs directly create the event into a new section, since if multiple APIs were to create the same event its redundant to repeat the event type/source values for each; what do you think?

timkimadobe · 2023-02-15T23:06:10Z

Documentation/event-reference.md

+
+| Key          | Value type    | Required | Description                |
+| ------------ | ------------- | -------- | -------------------------- |
+| locationHint | `boolean`     | Yes      | The Edge Network location hint to use when connecting to Edge Network. Property is set to `true` automatically; it is not user modifiable. |


That makes sense! Thank you, updated description section

For the Required column what do you think about updating the column name to Key Required or Mandatory Key? Since this doc is from the perspective of Edge extension's own event contract, all of the "Required"-ness should already be implied to be internal right?

Documentation/event-reference.md

timkimadobe · 2023-02-15T23:08:10Z

Documentation/event-reference.md

+
+This event signals that [Identity for Edge Network](https://github.com/adobe/aepsdk-edgeidentity-android) has completed [resetting all identities](https://developer.adobe.com/client-sdks/documentation/identity-for-edge-network/api-reference/#resetidentities) usually following a call to [`MobileCore.resetIdentities()`](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/MobileCore/api-reference.md). 
+
+When this event is received, the Edge extension queues it up and removes the cached internal state:store settings. If other events are queued before this event, these events will be processed first in the order they were received.


timkimadobe · 2023-02-15T23:40:52Z

Documentation/event-reference.md

+
+This event is a response to the [Edge request identity event](#edge-request-identity)) and provides the location hint being used by the Edge Network extension in requests to the Edge Network. The Edge Network location hint may be used when building the URL for Edge Network requests to hint at the server cluster to use.
+
+| Value | Behavior |


Removed table and added locationHint = true requirement in description

For adding a local href to getLoc Hint, did you mean adding a link to the getLocationHint API in the description for this section? I was thinking the link to Edge request identity event (which has a link to getLocationHint API) would be enough since that API actually creates that event, and not this response one

Documentation/event-reference.md

timkimadobe · 2023-02-15T23:41:07Z

Documentation/event-reference.md

+#### Data payload definition<!-- omit in toc -->
+
+| Key       | Value type    | Required | Description           |
+| --------- | ------------- | -------- | --------------------- |


Please see response to: https://github.com/adobe/aepsdk-edge-android/pull/44/files/71da2c1039e2c1a828b918b635e85afcfc53f8bb#r1107661756

timkimadobe · 2023-02-15T23:46:01Z

Documentation/event-reference.md

+
+| Event type                        | Event source                          |
+| --------------------------------- | ------------------------------------- |
+| com.adobe.eventType.edge          | This value is copied from the event being responded to; if not set or `null`, has a default value of com.adobe.eventSource.responseContent |


I was a bit confused for this one, since the dispatchResponse API is able to generate many different kinds of response events; for this section of "Edge event response" do we only want strictly the
Event type: com.adobe.eventType.edge and Event source: com.adobe.eventSource.responseContent and cover the other potential cases separately in other new sections?

for example dispatchResponse is able to use any eventSource value:

aepsdk-edge-android/code/edge/src/main/java/com/adobe/marketing/mobile/NetworkResponseHandler.java

Line 394 in 4501cc8

source = eventSource;

timkimadobe added 7 commits February 3, 2023 17:58

Add Events handled by Edge section

87a6260

WIP events dispatched

Update dispatched events

7138f16

WIP update for event reference

0b53b3a

Add Events handled by Edge section

a287f74

WIP events dispatched

Update dispatched events

014b0cc

WIP update for event reference

2579c8b

Merge branch 'edge-event-reference' of https://github.com/timkimadobe…

e143974

…/aepsdk-edge-android into edge-event-reference

Update dispatched events section

85503f3

timkimadobe marked this pull request as ready for review February 10, 2023 20:01

timkimadobe requested review from addb, cacheung, emdobrin and kevinlind February 10, 2023 20:03

timkimadobe changed the base branch from main to dev-v2.0.1 February 10, 2023 21:30

Update dispatched events section

a78e336

addb reviewed Feb 15, 2023

View reviewed changes

Documentation/event-reference.md Show resolved Hide resolved

Remove extraneous table

71da2c1

Fix event source value

timkimadobe commented Feb 15, 2023

View reviewed changes

addb reviewed Feb 15, 2023

View reviewed changes

Documentation/event-reference.md Show resolved Hide resolved

addb reviewed Feb 15, 2023

View reviewed changes

Documentation/event-reference.md Show resolved Hide resolved

addb reviewed Feb 15, 2023

View reviewed changes

Update based on feedback

b46478f

Standardize table header formatting for easier find and replace in the future Separate API creating event section Update API signature format to match standard java doc format

timkimadobe commented Feb 15, 2023

View reviewed changes

Remove variable event source section

a144253

Add handled events from edge event handle

2288b58

addb approved these changes Feb 17, 2023

View reviewed changes

timkimadobe merged commit f487fce into adobe:dev-v2.0.1 Feb 17, 2023

timkimadobe deleted the edge-event-reference branch February 17, 2023 21:51

timkimadobe mentioned this pull request Feb 17, 2023

Create Edge event reference & update API docs adobe/aepsdk-edge-ios#306

Merged

10 tasks

emdobrin added this to the v2.0.1 milestone Apr 20, 2023


		This event signals that [Identity for Edge Network](https://github.com/adobe/aepsdk-edgeidentity-android) has completed [resetting all identities](https://developer.adobe.com/client-sdks/documentation/identity-for-edge-network/api-reference/#resetidentities) usually following a call to [`MobileCore.resetIdentities()`](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/MobileCore/api-reference.md).

		When this event is received, the Edge extension queues it up and removes the cached internal state:store settings. If other events are queued before this event, these events will be processed first in the order they were received.


		This event is a response to the [Edge request identity event](#edge-request-identity)) and provides the location hint being used by the Edge Network extension in requests to the Edge Network. The Edge Network location hint may be used when building the URL for Edge Network requests to hint at the server cluster to use.

		\| Value \| Behavior \|

Conversation

timkimadobe commented Feb 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

Checklist:

Uh oh!

codecov bot commented Feb 10, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

timkimadobe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

addb Feb 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timkimadobe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

timkimadobe commented Feb 4, 2023 •

edited

Loading

codecov bot commented Feb 10, 2023 •

edited

Loading

addb Feb 15, 2023 •

edited

Loading