randyzwitch/adober

R package to access Adobe Analytics Reporting API v2

adober's Issues

Remove need to specify companyid as first parameter

Feels like it might be the case that we can infer the "zwitch0" parameter, optionally leaving ability for users to specify which value they want to use

Make package pass CRAN check

Even though package likely won't be put on CRAN, make it pass the checks as an indication of package quality

Remove individual methods in lieu of bulk?

Consider removing all of the one-off methods for specifying a single id or tag in a function. For example, the chances of a user being able to pass in the internal id for a calculated metric is probably outweighed by the greatly simplified code of not supporting it.

With bulk download, users can build implementation documentation, but without being able to specify a single id, the request payload will be slightly larger (which is likely only a problem for building a UI)

Figure out pagination

In #8, adding kwargs for pagination, but it's not clear that user would know to keep sending requests. Could potentially re-write functions to automatically paginate, but would need to read result to see if a next parameter passed

• GetCalculatedMetrics
• GetDateRanges
• GetReportSuites
• GetSegments
• GetUsers

Add return code checking to OAuth

In general, OAuth needs to be tightened up a lot. Need to check a valid return happens, so that when credentials already exist they aren't actually expired

Build URLs using urltools?

Might be better to use urltools instead of building strings using paste/sprintf
https://cran.r-project.org/web/packages/urltools/vignettes/urltools.html

Clean up OAuth (add auto-refresh, etc)

Related to #3

Currently, Adobe doesn't allow refreshing of tokens. When Adobe supports refreshing tokens, check for expired token, then refresh tokens to avoid needing to constantly authenticate via web process

Clean up OAuth for missing key/secret values

With caching for httr, should be allowed to call AdobeOAuth without putting in key/secret if credential file present.

Move globalCompanyId to adobe_get

Having globalCompanyId in each get function redundant; can just get the value from inside adobe_get for de-duplication

Refactor code to put all dataframe methods together

Move data frame methods from individual methods to common file, so that efficiencies begin to stand out in the code

Figure out JWT authentication

Understand what JWT (JSON Web Tokens) are and if this eliminates need to do webpage based authentication.

JWT appears to be the way to have a service account, so that no human intervention necessary. Workflow seems to be placing a private key into adobe.io, which creates a JWT; JWT gets passed back and forth?

If this is how it works, will need to figure out how to use same private key on Travis to enable CI.

Add "?includeType=shared" to CM/Segments/DateRange

https://github.com/AdobeDocs/analytics-2.0-apis/issues/67#issuecomment-467194169

Validate data.frame methods in presence of expansion keyword

As part of #8, a field expansion can be added, which adds more fields to the response. Because of auto-parsing in current functionality, these added fields will not parse well.

Consider how to parse these fields so that data frames come out correctly.

Set expansion arg to the set of values that get put cleanly into a data frame.

• CalculatedMetrics: reportSuiteName, ownerFullName, modified, tags, definition, compatibility
• Collections (ReportSuite): name, parentRsid, currency, calendarType, timezoneZoneinfo
• DateRanges: definition, ownerFullName, modified, tags
• Dimensions: tags
• Metrics: tags
• GetSegments: reportSuiteName, ownerFullName, modified, tags, compatibility, definition
• Add note in each function to the effect of "expansion parameter defaults to arguments that parse cleanly as data.frame; see docs for full set of args"

Improve docstrings

Docstrings are completely minimal, write docstrings for every function

Add remaining keyword arguments

Migrate existing code to use query parameter for building urls, then add additional keyword arguments shown for Swagger interface

• CalculatedMetrics
• Collections (GetReportSuites...simplify by removing rsid vs rsids?)
• DateRanges
• Dimensions
• Metrics
• Users
• Segments

Catch missing OAuth token

When AdobeRInternals$auth not present, function calls return Bad URL, colon is first character curl error, which is unfortunate. Test that values are not null before making curl request, so that error message can suggest calling AdobeOAuth

Remaining methods from Swagger UI

• Reports (POST)
• Segments (POST)
• Segments Validate (POST)
• Segments ID (PUT)
• Segments ID (DELETE)

Implement Segments API

Supersedes #11

Segments API covered here:
https://github.com/AdobeDocs/analytics-2.0-apis/blob/master/segments-guide.md
https://github.com/AdobeDocs/analytics-2.0-apis/blob/master/segments.md

It appears that Adobe really doesn't want people to programmatically create segments, instead suggesting users defer to using the UI. This looks like something to consider when building out this library; deleting segments probably pretty simple and useful for bulk removing of segments. Creating and Updating segments possibly a bit less so

Implement Freeform Table from Reports API

Supersedes #11

The reports endpoint is described here:
https://github.com/AdobeDocs/analytics-2.0-apis/blob/master/reporting-guide.md
https://github.com/AdobeDocs/analytics-2.0-apis/blob/master/reporting-multiple-breakdowns.md

How to set up debugger:
https://github.com/AdobeDocs/analytics-2.0-apis/blob/master/reporting-tricks.md

In general, it seems that multiple breakdowns requires walking over a set of reports, which is undesirable in a language like R. Will need to decide how to make separate functions for types of reports (time-series, ranked, etc.)

• anomaly detection, includePercentChange as kwarg
• anomaly detection, includePercentChange custom parsing for data frame
• auto-sort based on presence of daterange in dimension and/or anomalyDetection = TRUE
• create globalFilters kwarg
• create globalFilters function (validate if all filters have same structure)
• refactor globalFilters
• locale function
• search function
• evaluate remaining settings
• statistics function
• metricContainer: evaluate all
• rowContainer
• anchorDate
• remaining input assertions

Fill NULL with NA

Consider adding this line to each method that returns a single record, as NULL creates havoc in R when passing a list to as.data.frame

f3fea17#diff-194157484f130b02355b060240963689R56

Implement rest of Reports API besides Freeform Table

• fallout report
• pathing
• cohorts (TBD)
• histogram (TBD)
• venn (TBD)

License

Open question about how to license this if its commercial-only. Depending on how this package is distributed, could be relatively hard (i.e. don't submit to CRAN, keep GitHub repo private) to distribute.

https://softwareengineering.stackexchange.com/questions/68134/best-existing-license-for-closed-source-code/68150#68150

Need to think through this, though it's maybe not a huge idea

Check input types using assertions

Since R doesn't have type signatures, check types. Use assertthat or similar

• AdobeOAuth
• GetUserCompanyAccess
• GetCalculatedMetrics
• Collections
• DateRanges
• Dimensions
• Metrics
• Users
• Segments

Add return code checking to all functions

Currently, if functions error, they return NULL because the error passes through the dataframe parsing. Add checks/assertions to do this properly

Don't return JSON?

More I'm thinking about it, giving the choice of returning the raw data instead of just a table might not make any sense. In the end, R still inconvenient as hell to work with JSON, so what might people be wanting to do who use R AND still want to have something that's not a data frame?

Clean up dev hacks

Go through code and remove any global assignments, debugging statements, function exports, etc.